63

How can I specify optional dependencies in a pip requirements file?

According to the pip documentation this is possible, but the documentation doesn't explain how to do it, and I can't find any examples on the web.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
del
  • 6,341
  • 10
  • 42
  • 45
  • 4
    Great Q. -- a related q. would be how to define a set of requirements that should be attempted to be installed but not to consider installation a failure if they cannot be installed. I have a package that works better if numpy is installed but has a fallback if numpy can't compile for some reason. I would love to make it a default-installed but optional if failed requirement. – Michael Scott Asato Cuthbert May 24 '17 at 13:18

3 Answers3

31

Instead of specifying optional dependencies in the same file as the hard requirements, you can create a optional-requirements.txt and a requirements.txt.

To export your current environment's packages into a text file, you can do this:

pip freeze > requirements.txt

If necessary, modify the contents of the requirements.txt to accurately represent your project's dependencies. Then, to install all the packages in this file, run:

pip install -U -r requirements.txt

-U tells pip to upgrade packages to the latest version, and -r tells it to install all packages in requirements.txt.

Daniel Naab
  • 22,690
  • 8
  • 54
  • 55
  • 4
    I think you've misunderstood the question. 'pip freeze' will just print out all of the dependencies. What I want to know is how I can specify which dependencies are required and which are optional within the pip requirements file. – del Sep 08 '10 at 05:38
  • I see the reference in the docs I think you're referring to, but I'm not sure it's possible in one requirements file... although you could have two dependency files, one which lists optional dependencies. I'll modify my answer – Daniel Naab Sep 08 '10 at 05:51
  • Thanks - this is the approach I was already taking, but reading the bit about optional dependencies in the doc made me think there might be a better way to do it. – del Sep 08 '10 at 07:25
  • Correct me if i am wrong, but i think what was implied by the question was specifying dependencies for a package in the form ``` pip install channels['daphne'] ``` here daphne is additional installed as a dependency for channels. How can such dependencies be specified in the pip file – Brian Obot Feb 06 '23 at 19:15
30

In 2015 PEP-0508 defined a way to specify optional dependencies in requirements.txt:

requests[security]

That means that yourpackage needs requests for its security option. You can install it as:

pip install yourpackage[security]
anatoly techtonik
  • 19,847
  • 9
  • 124
  • 140
  • 4
    You can configure one of these "extras" using the [`extras_require` argument](http://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies) for the `setup` function in `setuptools`. You can see in [the requests setup.py](https://github.com/requests/requests/blob/3c1d36b827417fdeaf5a1c106129de30dac371d7/setup.py#L98) how the `security` "extra" is configured. – gene_wood Feb 13 '18 at 19:08
  • Related: [How to install python module extras with pip requirements.txt file](https://stackoverflow.com/q/36490897/99377). – Jon-Eric Jun 30 '20 at 14:16
  • When I try this I just get a lot of errors like `Collecting pytest-cov[tests] ... WARNING: pytest-cov 2.10.0 does not provide the extra 'tests'` , `Collecting numba[fast]<0.47 ... WARNING: numba 0.46.0 does not provide the extra 'fast'"` – endolith Aug 10 '20 at 03:47
  • 3
    Oh I think the problem is that in the requirements.txt, the brackets indicate an "extra" of the dependency, while I was interpreting it to mean "this is only a dependency of my package if my package is installed with that extra" – endolith Aug 10 '20 at 04:24
  • 1
    If you are installing from github, you can use something like `pip install "requests[security] @ git+ssh://git@github.com/psf/requests.git"` instead – Flair Dec 11 '20 at 18:05
-2

You are misunderstanding the documentation; it's not as clear as it could be. The point in the documentation is that with a requirements file you can feel free to specify your full recommended working set of packages, including both necessary dependencies and optional ones.

You can add comments (lines beginning with #) to distinguish the two to humans, but pip makes no distinction. You can also have two requirements files, as Daniel suggests.

Carl Meyer
  • 122,012
  • 20
  • 106
  • 116
  • 18
    You aren't really free to include both the required and optional dependencies in a requirements file because 'pip install' will immediately abort if any of the packages in the file fail to install. It seems that using two separate requirements files is the only correct solution. – del Sep 08 '10 at 07:43