Python package requirements: Usage of version specifiers == and >=

Question

I'm looking for best practices, do's and don'ts regarding version specifications in requirement's files for pip in python packages.

Assume a python package which depends on some other modules. A minimum version is required for most of them. At least it is know to the maintainers, that the code works with a least, e.g. six 1.7

Now, it is possible to define the requirement in different ways:

• six>=1.7.0 The software has been tested with this version and it is assumed that it will also with future versions
• six==1.7.0 We require the exact version, the package has been tested with. The software has not been tested with all future versions of the module, thus we can't guarantee it will work for those.
• six==1.9.0 We just test it with the most recent version and require it.

I do have an inhibition to require an exact version, as it may break other packages requirements and seems bad practice for me. On the other hand, the package has not been tested with all versions of six above 1.7.0.

Are there any guidelines regarding package version requirements and the usage of == against >=?

Answer 1

Based on my experience as developer, packager (package maintainer for distributions) and software maintainer I came to the following interpretation / recommendations:

• install_requires: The dependencies listed in install_requires are checked during runtime (!) by pkg_resources. They are hard dependencies. They can (should?) contain a required minimum version number, but not an exact version unless very good reasons are given. More supported versions are generally more useful, maximum version numbers are usually a nightmare.
• extras_requires list optional requirements (recommendations), which are not needed for the core functionality, but for some extras, or are optional, enhancing the functionality. If a software does not properly work without it, it should go to install_requires.
• requirements.txt Some maintainers set it the same with install_requires, some others don't use it at all. It can be used to recommend specific versions of requirements, which are best tested. This is of course not useful at all for packaging, but for setups in virtualenvs and similar.

Packagers usually do not use the information from requirements.txt, but from install_requires and extras_requires.