Skip to content

Commit

Permalink
Better explain role of existing requirements.txt (#1369)
Browse files Browse the repository at this point in the history
This commit adds an explanation of the role of existing requirements.txt
files to the README.

I found this very unclear and opened #1358 because of my confusion. The
existing short note that requirements.txt "might interfere" didn't
really help me. I'm not sure how common my confusion is, but I hope my
changes make things clearer to new users (assuming what I've written is
in fact correct!)

(In addition to my additions, I moved the "Updating requirements"
section up in the doc, since it seems like a core workflow.)
  • Loading branch information
mikepqr committed Apr 27, 2021
1 parent 34f1b9d commit e8982fb
Showing 1 changed file with 41 additions and 31 deletions.
72 changes: 41 additions & 31 deletions README.rst
Expand Up @@ -30,7 +30,6 @@ even when you've pinned them. You do pin them, right? (In building your Python
:target: https://pypi.org/project/pip-tools/
.. _You do pin them, right?: http://nvie.com/posts/pin-your-packages/


Installation
============

Expand Down Expand Up @@ -62,9 +61,11 @@ 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.
**Note**: If ``pip-compile`` finds an existing ``requirements.txt`` file that
fulfils the dependencies then no changes will be made, even if updates are
available. To compile from scratch, first delete the existing
``requirements.txt`` file, or see `Updating requirements`_ for alternative
approaches.

Requirements from ``setup.py``
------------------------------
Expand Down Expand Up @@ -130,6 +131,42 @@ And it will produce your ``requirements.txt``, with all the Django dependencies

.. _it's easy to write one: https://packaging.python.org/guides/distributing-packages-using-setuptools/#configuring-your-project

.. _Updating requirements:

Updating requirements
---------------------

``pip-compile`` generates a ``requirements.txt`` file using the latest versions
that fulfil the dependencies of ``setup.py`` or ``requirements.in``.

If ``pip-compile`` finds an existing ``requirements.txt`` file that fulfils the
dependencies then no changes will be made, even if updates are available.

To force ``pip-compile`` to update all packages in an existing
``requirements.txt``, run ``pip-compile --upgrade``.

To update a specific package to the latest or a specific version use the
``--upgrade-package`` or ``-P`` flag:

.. code-block:: bash
# only update the django package
$ pip-compile --upgrade-package django
# update both the django and requests packages
$ pip-compile --upgrade-package django --upgrade-package requests
# update the django package to the latest, and requests to v2.0.0
$ pip-compile --upgrade-package django --upgrade-package requests==2.0.0
You can combine ``--upgrade`` and ``--upgrade-package`` in one command, to
provide constraints on the allowed upgrades. For example to upgrade all
packages whilst constraining requests to the latest version less than 3.0:

.. code-block:: bash
$ pip-compile --upgrade --upgrade-package 'requests<3.0'
Using hashes
------------

Expand Down Expand Up @@ -162,33 +199,6 @@ version 8.0, ``pip-compile`` offers ``--generate-hashes`` flag:
--hash=sha256:7c3dca29c022744e95b547e867cee89f4fce4373f3549ccd8797d8eb52cdb873 \
# via django
Updating requirements
---------------------

To update all packages, periodically re-run ``pip-compile --upgrade``.

To update a specific package to the latest or a specific version use the
``--upgrade-package`` or ``-P`` flag:

.. code-block:: bash
# only update the django package
$ pip-compile --upgrade-package django
# update both the django and requests packages
$ pip-compile --upgrade-package django --upgrade-package requests
# update the django package to the latest, and requests to v2.0.0
$ pip-compile --upgrade-package django --upgrade-package requests==2.0.0
You can combine ``--upgrade`` and ``--upgrade-package`` in one command, to
provide constraints on the allowed upgrades. For example to upgrade all
packages whilst constraining requests to the latest version less than 3.0:

.. code-block:: bash
$ pip-compile --upgrade --upgrade-package 'requests<3.0'
Output File
-----------

Expand Down

0 comments on commit e8982fb

Please sign in to comment.