What is the difference between `extras_require()` and `install_requires()` in setup.py?

According to the setuptools documentation,

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.


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.

Leave a Comment