Django Split Settings

1.3.2 · active · verified Thu Apr 16

django-split-settings helps organize Django settings into multiple files and directories, allowing for easier overriding and modification. It supports wildcards, optional settings files, and includes/merges settings from various sources. The current version is 1.3.2, with a release cadence that addresses bugfixes and adds support for newer Python and Django versions.

Common errors

```
TypeError: include() got an unexpected keyword argument 'globals'
```
cause Using `globals=globals()` or similar keyword arguments with `include()` in versions 1.3.0 or newer.

fix The `include` signature changed. Replace `globals=globals()` with `scope=globals()`. For example, `include('file.py', scope=globals())`.
```
ModuleNotFoundError: No module named 'split_settings.tools'
```
cause The `django-split-settings` package is not installed in the current Python environment or you are trying to import from an incorrect path.

fix Install the package using `pip install django-split-settings`. Ensure your virtual environment is activated if applicable.
```
FileNotFoundError: [Errno 2] No such file or directory: 'settings/local.py'
```
cause You are attempting to `include()` a settings file that does not exist, and you have not wrapped the path with `optional()`.

fix Wrap the path of the potentially missing file with `optional()`: `include(optional('settings/local.py'))`.

Warnings

breaking The `include()` function signature changed in version 1.3.0. Keyword arguments like `globals` or `locals` are no longer supported. Instead, use the `scope` keyword argument for explicit scope passing.
Fix: Replace `include('file.py', globals=globals())` with `include('file.py', scope=globals())`. If you were passing other unsupported keyword arguments, remove them as they were not functional prior to 1.3.0 anyway.
breaking Python 3.8 support was dropped in version 1.3.0. Users on Python 3.8 will need to upgrade their Python version to 3.9 or newer to use django-split-settings >= 1.3.0.
Fix: Upgrade your Python environment to 3.9, 3.10, 3.11, or 3.12.
gotcha Attempting to include a non-existent file without wrapping it in `optional()` will raise a `FileNotFoundError`. This is common for local development override files (e.g., `local.py`) that are not committed to version control.
Fix: Always wrap paths to potentially missing settings files with `optional()`, for example: `include(optional('local.py'))`.
breaking Python 2 and Django 2.0 support was dropped in version 1.0.0. Projects using these older versions must remain on django-split-settings < 1.0.0.
Fix: Upgrade your Django and Python versions to modern supported releases, or pin `django-split-settings<1.0.0`.

Install

pip install django-split-settings Install stable version

Imports

include
wrong:
```
from split_settings.tools import include, optional, apply_modifiers
```
correct:
```
from split_settings.tools import include
```
While 'optional' and 'apply_modifiers' are also from 'split_settings.tools', 'include' is the primary function for splitting settings. Importing all three in a single statement is not wrong, but 'include' is the most essential and frequently used.

optional

from split_settings.tools import optional

Quickstart

This quickstart demonstrates a typical setup for django-split-settings. In your `settings/__init__.py` file (or directly in your main `settings.py`), you import `include` and `optional`. You then use `include` to pull in other settings files, often starting with a `base.py` for common configurations, followed by environment-specific or local override files. The `optional()` wrapper ensures that your application doesn't crash if an included file (e.g., a developer's `local.py`) doesn't exist.

import os
from split_settings.tools import include, optional

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# Include settings from base.py
include(optional('base.py'))

# Include environment-specific settings (e.g., local.py, production.py)
# The '*' wildcard includes all matching files.
# Using 'optional' prevents errors if a file doesn't exist.
# 'settings/*' would include files in a 'settings' subdirectory.
include(
    optional('environment/*.py'),
    optional('local.py')
)

# Example of a setting, potentially overridden by included files
DEBUG = True

ALLOWED_HOSTS = ['*']

# Example of how you might structure settings files:
#
# settings/
# ├── __init__.py  (This file)
# ├── base.py      (Common settings)
# ├── environment/
# │   ├── dev.py   (Development environment settings)
# │   └── prod.py  (Production environment settings)
# └── local.py     (Local overrides, usually excluded from VCS)

view raw JSON →