install_requires vs requirements files¶
install_requires is a setuptools
setup.py keyword that
should be used to specify what a project minimally needs to run correctly.
When the project is installed by pip, this is the specification that is
used to install its dependencies.
For example, if the project requires A and B, your
install_requires would be
install_requires=[ 'A', 'B' ]
Additionally, it’s best practice to indicate any known lower or upper bounds.
For example, it may be known, that your project requires at least v1 of ‘A’, and v2 of ‘B’, so it would be like so:
install_requires=[ 'A>=1', 'B>=2' ]
It may also be known that project A follows semantic versioning, and that v2 of ‘A’ will indicate a break in compatibility, so it makes sense to not allow v2:
install_requires=[ 'A>=1,<2', 'B>=2' ]
It is not considered best practice to use
install_requires to pin
dependencies to specific versions, or to specify sub-dependencies
(i.e. dependencies of your dependencies). This is overly-restrictive, and
prevents the user from gaining the benefit of dependency upgrades.
Lastly, it’s important to understand that
install_requires is a listing of
“Abstract” requirements, i.e just names and version restrictions that don’t
determine where the dependencies will be fulfilled from (i.e. from what
index or source). The where (i.e. how they are to be made “Concrete”) is to
be determined at install time using pip options. 1
install_requires defines the dependencies for a single project,
Requirements Files are often used to define
the requirements for a complete Python environment.
install_requires requirements are minimal, requirements files
often contain an exhaustive listing of pinned versions for the purpose of
achieving repeatable installations of a complete
install_requires requirements are “Abstract”, i.e. not associated
with any particular index, requirements files often contain pip
--find-links to make requirements
“Concrete”, i.e. associated with a particular index or directory of
install_requires metadata is automatically analyzed by pip during an
install, requirements files are not, and only are used when a user specifically
installs them using
python -m pip install -r.
For more on “Abstract” vs “Concrete” requirements, see https://caremad.io/posts/2013/07/setup-vs-requirement/.