Difference between extras_require() and install_requires() in setup.py?

Question

I am trying to understand the difference between extras_require() and install_requires() in setup.py but couldn't get it. Both are used for installing Python dependencies, but what's the difference between them?

Answer 1

According to the setuptools documentation,

extras_require
A dictionary mapping names of “extras” (optional features of your project) to strings or lists of strings specifying what other distributions must be installed to support those features.

and

install_requires
A string or list of strings specifying what other distributions need to be installed when this one is.

The section on Declaring “Extras” (optional features with their own dependencies) elaborates on this:

Sometimes a project has “recommended” dependencies, that are not required for all uses of the project. For example, a project might offer optional PDF output if ReportLab is installed, and reStructuredText support if docutils is installed. These optional features are called “extras”, and setuptools allows you to define their requirements as well. In this way, other projects that require these optional features can force the additional requirements to be installed, by naming the desired extras in their install_requires.

The biggest difference is that the requirements in extras_require are only installed as needed:

These requirements will not be automatically installed unless another package depends on them (directly or indirectly) by including the desired “extras” in square brackets after the associated project name. (Or if the extras were listed in a requirement spec on the EasyInstall command line.)

So to summarize:

• If the dependency is necessary to run your project, put it in install_requires. They will always be installed.
• If your project has optional features which add dependencies, put those dependencies in extras_require. Those dependencies will not be installed unless that feature is called for by the user or another package.

Answer 2

install_requires are the dependency packages which are installed no matter what.

pip install mypackage

extras_require are optional, and need to be specified at install time. This is a feature of pip.

pip install mypackage[extra]
pip install mypackage[develop]
pip install mypackage[extra,develop]

A good example is https://pypi.org/project/imgui/ which allows you to choose a specific graphics backend.

Refer to PEP 508 to see all possible selectors you can use; e.g. ; python_version < "2.7".

Answer 3

I'm not sure of the official usage, but I use extras_require() to specify conditional dependencies.

In my case -

extras_require={":python_version<'3.5'": ["scandir"]}

Theoretically, this should be available via install_requires() itself, but it only works as it should starting version X.XX (several claims as to which version starts getting it right) of setuptools.

This article explains it nicely: Conditional Python Dependencies