Getting started

django-environments is a very light-weight package that aims to make your life as Django developer easier. While it advocates certain patterns in setting up your Django project (e.g. an “inheritance model” for your settings), there are very few things that django-environments enforces on you.

To demonstrate, here is a quick-start guide to getting a first-time Django project up and running together with django-environments.

Starting a basic Django project

First, let’s create a virtualenv with Django and django-environments installed and initialize an empty Django project:

$ mkvirtualenv djenv-example
$ pip install Django # installs latest version of Django
$ cd ~/dev/ && mkdir djenv-example # or wherever you like your project to live
$ djadmin startproject example djenv-example

This should now give you something like this:

djenv-example/
    example/
        __init__.py
        settings.py
        urls.py
        wsgi.py
    manage.py

Install django-environments

$ pip install django-environments
$ source djenvlib.sh
$ type djenv | head -n 1
djenv is a function # it works!

See also

Installation

Enable django-environments in your Django project

To enable django-environments for your Django project, add one line to the top of your settings.py:

from djenv.settings.core import *
# ...

Note

This adds four custom settings that make further configuration easier. See djenv.settings.core for details.

Use the django-environments setproject command to set the PROJECT_ROOT:

$ setproject ~/dev/djenv-example/
Warning: no django projects found
$ echo $PROJECT_ROOT
/Users/yuri/dev/djenv-example

Note

The warning is because django-environments expects a settings package (containing an __init__.py) instead of a single settings.py. This is a known issue.

See also Settings management.

Now use the djenv command to tell django-environments the name of our DJANGO_PROJECT, and it will respond with some useful environment information:

$ djenv example
Welcome to djenv-example/example. Environment info:
PROJECT_ROOT: '/Users/yuri/dev/djenv-example'
DJANGO_PROJECT: 'example'
DJANGO_SETTINGS_MODULE: 'example.settings'
PYTHONPATH: '/Users/yuri/dev/djenv-example:/Users/yuri/dev/djenv-example/lib:'

That is pretty much it!

Useful commands

You can now use handy commands to navigate within your project, such as going to your Django project directory using cdjango:

$ cdjango && pwd
/Users/yuri/dev/djenv-example/example

or back to the project root using cdroot:

$ cdroot && pwd
/Users/yuri/dev/djenv-example

Note

It may not surprise you that these commands were inspired by some of the very useful commands that virtualenvrapper provides, such as cdvirtualenv and cdsitepackages.

If you quickly want know what the value of a Django setting is given the currently active django settings module, use the get_django_setting command:

$ get_django_setting ROOT_URLCONF
example.urls

See also

A full list of available commands

Next steps

Now that you have the basics installed, you can further optimize and organize your Django settings. For example, the default Django 1.7 settings.py defines a BASE_DIR:

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

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
    }
}

But using django-environments, you can simply use PROJECT_ROOT:

from djenv.settings.core import * # sets PROJECT_ROOT
# ...

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(PROJECT_ROOT, 'db.sqlite3'),
    }
}

In this particular case though, you could even use djenv.settings.database:

from djenv.settings.core import *
from djenv.settings.database import * # defines DATABASES_DEFAULT
# ...

DATABASES['default'] = DATABASES_DEFAULT['sqlite']

You should also consider organizing your settings in a hierarchical structure – see Settings management.