install_requires vs Requirements files¶

install_requires¶

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 like so:

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]

Requirements files¶

Requirements Files described most simply, are just a list of pip install arguments placed into a file.

Whereas install_requires defines the dependencies for a single project, Requirements Files are often used to define the requirements for a complete python environment.

Whereas 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 environment.

Whereas install_requires requirements are “Abstract”, requirements files often contain pip options like --index-url or --find-links to make requirements “Concrete”. [1]

Whereas 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 pip install -r.