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

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?

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.

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".

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

This is a very good question. I was looking for an answer myself, but couldn't find one that satisfied me. So after gaining some experience, here are some examples that can help better understand:

Suppose our package is foo and it integrates with a users package bar, extending it's functionality. Our package foo cannot work without bar so it seems like it should be in install_requires, but there is a problem with that. If, for example, user had version 1.1 of bar installed, then installed our package foo - our package may install version 1.2 of bar which will override users version. Instead, we put bar in bar section in extras_require. In this case user can safely install foo, knowing that it will integrate with his existing version of bar. But what if the user doesn't have bar installed? In this case the user will run pip install foo[bar].

Another good example is tests. Very often the tests of your packge use packages like mock or spceific data types (like DataFrame) which are not mandatory for the use of the package itself. In this case, you can put all packages required for tests in test section in extras_require. When you want to run tests in a virtual environment (tox), you can simply write deps=my_package[tests] in the tox.ini file.

I hope this answer helps.