Skip to main content

Let Django use settings from an arbitrary Python file instead of an importable module

Project description


Let Django use settings from an arbitrary Python file instead of an importable module.

As per James Pic’s idea posted on the django-developers mailing list.


Python 3.5 to 3.8 and Django 1.11 to 3.0 are supported.


  1. Install with pip install django-settings-file.

  2. Edit your and to swap out Django’s default logic for setting DJANGO_SETTINGS_MODULE to instead do:

    import django_settings_file
  3. Add os.environ.setdefault('DJANGO_SETTINGS_FILE', '/path/to/') before the setup() call, unless you can be sure DJANGO_SETTINGS_FILE will always be defined in your environment. You might need to figure out the path relative to your with some os.path manipulation.

  4. Run it! If DJANGO_SETTINGS_MODULE is defined, it will raise a DjangoSettingsFileError with a message about how only DJANGO_SETTINGS_FILE is allowed now. If DJANGO_SETTINGS_FILE is not defined, it will also fail with a DjangoSettingsFileError with a message about defining it. Otherwise Django should start with the settings!

How it works

django-settings-file imports the contents of the specified file using the import machinery available on your Python version (different logic for 2 and 3) and copies it contents into its own module, which Django sees as the settings file defined via the traditional DJANGO_SETTINGS_MODULE. Nothing about Django is really touched, it’s just a hacky module.


  • If the Python file defined by DJANGO_SETTINGS_FILE tries to do any imports, the directory the file is in will not be on PYTHONPATH, so the author of the settings file might get some surprises.
  • Additionally, you might experience other problems from loading a file whilst it’s not on PYTHONPATH.
  • If you want your settings file to extend another one, it will probably find it easiest to import the base one from a location on PYTHONPATH, otherwise it too will have to do use the same import ‘hacks’ to load the default settings.
  • File paths are not portable between operating systems, so you may need logic to support both Unix and Windows at once.
  • File paths are not portable between .py and .pyc files. In most cases this means a .pyc file will not be used for settings since it can’t be guaranteed to be there, slightly slowing down import time.
  • DJANGO_SETTINGS_MODULE and DJANGO_SETTINGS_FILE can’t both be used by the same project, since the module is required for the file-based logic. You might be able to allow them both with extra logic, pull requests accepted.
  • ¯\_(ツ)_/¯ - this is kind of unknown territory, this library has not been tested in any real project, just with the example project in the test folder.


2.1.0 (2019-12-19)

  • Update Python support to 3.5-3.8, as 3.4 has reached its end of life.
  • Converted setuptools metadata to configuration file. This meant removing the __version__ attribute from the package. If you want to inspect the installed version, use importlib.metadata.version("django-settings-file") (docs / backport).
  • Tested with Django 3.0. No changes were required for compatibility.

2.0.1 (2019-04-28)

  • Tested with Django 2.2. No changes were required for compatibility.

2.0.0 (2019-02-02)

  • Drop Python 2 support, only Python 3.4+ is supported now.
  • Drop Django 1.8, 1.9, and 1.10 support. Only Django 1.11+ is supported now.

1.0.0 (2017-04-14)

  • First version, supporting DJANGO_SETTINGS_FILE instead of DJANGO_SETTINGS_MODULE

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-settings-file, version 2.1.0
Filename, size File type Python version Upload date Hashes
Filename, size django_settings_file-2.1.0-py3-none-any.whl (4.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-settings-file-2.1.0.tar.gz (6.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page