diff --git a/README.rst b/README.rst index adde47078..ffca152ed 100644 --- a/README.rst +++ b/README.rst @@ -34,8 +34,8 @@ even when you've pinned them. `You do pin them, right?`_ Installation ============ -As part of a Python project's environment tooling (similar to ``pip``), it's -recommended to install ``pip-tools`` in each project's `virtual environment`_: +Similar to ``pip``, ``pip-tools`` must be installed in each of your project's +`virtual environments`_: .. code-block:: bash @@ -45,7 +45,7 @@ recommended to install ``pip-tools`` in each project's `virtual environment`_: **Note**: all of the remaining example commands assume you've activated your project's virtual environment. -.. _virtual environment: https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments +.. _virtual environments: https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments Example usage for ``pip-compile`` ================================= @@ -57,6 +57,11 @@ Run it with ``pip-compile`` or ``python -m piptools compile``. If you use multiple Python versions, you can run ``pip-compile`` as ``py -X.Y -m piptools compile`` on Windows and ``pythonX.Y -m piptools compile`` on other systems. +``pip-compile`` should be run from the same virtual environment as your +project so conditional dependencies that require a specific Python version, +or other environment markers, resolve relative to your project's +environment. + **Note**: ensure you don't have ``requirements.txt`` if you compile ``setup.py`` or ``requirements.in`` from scratch, otherwise, it might interfere. @@ -303,6 +308,10 @@ Run it with ``pip-sync`` or ``python -m piptools sync``. If you use multiple Python versions, you can also run ``py -X.Y -m piptools sync`` on Windows and ``pythonX.Y -m piptools sync`` on other systems. +``pip-sync`` must be installed into and run from the same virtual +environment as your project to identify which packages to install +or upgrade. + **Be careful**: ``pip-sync`` is meant to be used only with a ``requirements.txt`` generated by ``pip-compile``.