Django Requirements Best Practice#

Two minutes read.

Note

In this discussion, dependencies and requirements mean the same thing and are interchangeable. In Python, by convention, dependencies are stored in a requirements.txt file.

Documentation dependencies are outside the scope of this discussion.

Although there are many ways to configure the Django requirements file structure, there is a commonality in many experienced developers’ approaches or preferred guidelines.

  1. Version control dependencies.

  2. Follow The 12 Factor App [1] principles of storing Dependencies.

  3. Do not repeat yourself.

The 12 Factor guideline focus of this discussion is number two, Dependencies.

By following this guideline, we ensure strict separation between environment dependencies.

Extract from 12 Factor Dependencies: [2]#

A twelve-factor app never relies on the implicit existence of system-wide packages.

It declares all dependencies, completely and precisely, via a dependency declaration manifest.

Furthermore, it uses a dependency isolation tool during execution to ensure no implicit dependencies “leak in” from the surrounding system.

The full and explicit dependency specification is applied uniformly to both production and development.

Dependency Files Structure#

From the outset, having a suitable dependency file structure has many benefits as the project grows. Some key benefits are:

  1. It simplifies the setup for developers new to the app.

  2. Separation of concerns; see file structure below.

  3. The requirements files are DRY [3].

  4. Eliminate adding unrecorded dependencies to a virtual environment on a local machine.

  5. Eliminate errors with local dev dependencies leaking and breaking production.

  6. The requirements file size is smaller and more manageable.

Django Requirements Files#

Following the same logic applied to our settings configuration, our virtual/operating environments should have separate requirements.txt files.

Each environment has different dependencies; for example, we would not run django-debug-toolbar [4] in production.

Our requirements file structure mirrors the settings file structure.

Requirements File Structure#
config
  └── requirements
       ├── base.txt
       ├── local.txt
       ├── production.txt
       ├── staging.txt
       └── test.txt

Why did we put requirements into the config folder?#

While this arrangement is not required for a 12 Factor App [1], from a logical perspective, we use dependency/requirements files as configuration settings for our virtual/operating environments.

For that reason, we have chosen to group dependencies under the config folder.

requirements_dev.txt keeps it simple#

Splitting all the dependencies into separate operating environments can add some complexity to, for example, setting up a local environment with the ability to test.

The requirements_dev.txt reduces complexity for developers. Here, dependency imports from local and test environments keep it simple for most developer use cases.

requirements-dev.txt#
-r config/requirements/local.txt
-r config/requirements/test.txt
-r docs/requirements.txt

Footnotes