57

When installing my python package, I want to be able to tell the user about various optional dependencies. Ideally I would also like to print out a message about these optional requirements and what each of them do.

I haven't seen anything yet in the docs of either pip or docutils. Do tools these support optional dependencies?

Mike Cooper
  • 2,928
  • 2
  • 26
  • 29
  • Possible duplicate of: http://stackoverflow.com/questions/3664478/optional-dependencies-in-a-pip-requirements-file – Gregg Jun 04 '11 at 17:04
  • If they're optional, they're not strictly dependencies, are they? – Vinay Sajip Jun 05 '11 at 12:46
  • 4
    I call them optional dependencies, because that is what ubuntu's package manager call them. They are not strictly required, but if they are installed, the program can use them. – Mike Cooper Jun 05 '11 at 17:19
  • 2
    Not a duplicate of 3664478, the other asker explicitly wanted pip-requirements which isn't a very natural way to handle this. – Tobu Dec 03 '12 at 11:00

3 Answers3

57

These are called extras, here is how to use them in your setup.py, setup.cfg, or pyproject.toml.

The base support is in pkg_resources. You need to enable distribute in your setup.py. pip will also understand them:

pip install 'package[extras]'
Aaron V
  • 6,596
  • 5
  • 28
  • 31
Tobu
  • 24,771
  • 4
  • 91
  • 98
  • 19
    Is there a standardised way to view which extras are available? – Sean1708 Oct 10 '15 at 12:32
  • 1
    @Sean1708 No, pip doesn't have a feature like that today. One workaround is to inspect the source code's `setup.py` file for extras. Another is to check the "extras" key in the installed package's `-.dist-info/metadata.json` inside `site-packages` (or wherever you have the package installed). – Taylor D. Edmiston Jun 21 '17 at 20:06
  • 1
    Updated documentation link: https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies – Eric Smith Mar 07 '22 at 19:49
  • For anyone else who ends up here because of 'no matches found' when trying to install an optional dependency, it only worked for me once I added the quotes seen in this answer. – jack Aug 14 '23 at 23:28
16

Yes, at stated by @Tobu and explained here. In your setup.py file you can add a line like this:

extras_require = {
        'full': ['matplotlib', 'tensorflow', 'numpy', 'tikzplotlib']
    }

I have an example of this line here.

Now you can either install via PIP basic/vanilla package like pip install package_name or the package with all the optional dependencies like pip install package_name[full]

Where package_name is the name of your package and full is because we put "full" in the extras_require dictionary but it depends on what you put as a name.

If someone is interested in how to code a library that can work with or without a package I recommend this answer

J Agustin Barrachina
  • 3,501
  • 1
  • 32
  • 52
11

Since PEP-621, this information is better placed in the pyproject.toml rather than setup.py. Here's the relevant specification from PEP 621. Here's an example snippet from a pyproject.toml (credit to @GwynBleidD):

[project.optional-dependencies]
test = [
  "pytest < 5.0.0",
  "pytest-cov[all]"
]
lint = [
  "black",
  "flake8"
]
ci = [
  "pytest < 5.0.0",
  "pytest-cov[all]",
  "black",
  "flake8"
]

A more complete example is found in the PEP

Jake Stevens-Haas
  • 1,186
  • 2
  • 14
  • 26
  • 9
    You can then install them with e.g. `pip install .[test]` or `pip install your_package[lint]` – jan-glx Oct 05 '22 at 14:11