3

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 >=?

Vadim Kotov
  • 8,084
  • 8
  • 48
  • 62
sebix
  • 2,943
  • 2
  • 28
  • 43
  • keep both versions: one specifies minimal requirements `>=` and contains only direct dependencies (hand-written), another one uses exact tested versions for all 3rd-party packages that are generated automatically (`pip-compile`) – jfs Sep 20 '15 at 16:15
  • So I should recommend to install the exact versions if possible, and additionally require minimal versions? The recommended exact versions can be put in a requirements file for `pip -r`. But how to deal with the minimal requirements, put it in setuptools' `install_requires`? – sebix Sep 20 '15 at 19:12
  • 1
    different use-cases may require different solutions; it is not "either or": use exact versions for yourself, to enable a reproducible environment. You can't control what versions might be available in other environments -- don't set any restrictions unless you must (i.e., if you know that it doesn't work before a specific version) e.g., put yourself in the shoes of a package maintainer for a distribution: it might be useful to know (e.g., by visiting CI site) what exact versions are tested 1.9.0 but it is best if your package supports the current/future stable versions i.e., `six>=1.7` is ok. – jfs Sep 20 '15 at 20:32
  • Would you mind writing this into an answer? Otherwise I will do myself, but I think your comment is basically the answer. – sebix Aug 13 '17 at 19:52
  • it is a vast topic, the comment just scratches the surface. You know your specific use-case better. If you think you've found a solution, you could post your own answer — [it is explicitly encouraged](https://stackoverflow.com/help/self-answer) – jfs Aug 13 '17 at 20:22
  • @jfs I did so now, two years later. – sebix Sep 17 '17 at 16:05

1 Answers1

3

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.

sebix
  • 2,943
  • 2
  • 28
  • 43