A Django project template is the natural solution when the default Django project format is not enough anymore. Learn how to make your own in this tutorial.

What is a Django project template?

A rather obscure feature of Django is the ability to install a Django project starting from a template, that is, from a custom directory structure.

This is convenient when the default project format is not enough anymore (it isn't as soon as you want to deploy in production, trust me), or when you reached the point where you repeat the same configurations over and over for a lot of Django projects.

A Django project template is nothing more than a pre-defined project with a custom directory structure, and you can create one for yourself in minutes.

An example of a popular Django template is django-cookiecutter. With a wide range of features and configurations ready for rock-solid production deployments, django-cookiecutter is the way to go for almost any new Django project.

However, django-cookiecutter sometimes is simply too much, especially for beginners, and a simpler Django template can help you to grasp the basics before going bigger with django-cookiecutter.

In the next sections you'll learn how to build your own template.

How to create your own Django project template

To start off create a Python virtual environment in a folder of choice and install Django (note that they are four separate commands):

mkdir project-name && cd $_
python3 -m venv venv
source venv/bin/activate
pip install django

Then create a new Django project with:

django-admin startproject project_name .

Pay attention to the name: it should be exactly project_name. Once done open the project in an editor.

(Note that in this example I used project-name for the outer folder and project_name for the project name).

Now you should go through every file in the project and replace every occurrence of project_name with {{ project_name }} (a sed one liner will do).

The files you'll need to adjust are:

• manage.py
• settings.py
• wsgi.py
• asgi.py

As you might have guessed {{ project_name }} is a placeholder variable. For example, in manage.py you'll change this:

# manage.py

def main():
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project_name.settings')
    try:
# omit

to this:

# manage.py

def main():
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', '{{ project_name }}.settings')
    try:
# omit

In wsgi.py change this:

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project_name.settings')

to this:

os.environ.setdefault('DJANGO_SETTINGS_MODULE', '{{ project_name }}.settings')

And so on.

In addition you might also want to adjust any configuration you wish, or even better, split the Django settings in separate files for development, testing, and production. You can see an example here.

Before moving to the next section don't forget to remove the virtual environment from the template project.

How to create a Django project from your template

With the template project in place you're now ready to put it to use.

Create a new Python virtual environment in a different folder and install Django:

mkdir new-django-project && cd $_
python3 -m venv venv
source venv/bin/activate
pip install django

Now instead of running django-admin startproject as it is we'll pass the --template flag for installing from our template. Suppose you created the template in your home directory ~/project-name, you'd run:

django-admin startproject --template ~/project-name new_django_project .

This command will create your new Django project, starting from the template.

(Note that in this example I used new-django-project for the outer folder and new_django_project for the project name).

Now as convenient it could be, you might wonder if there's a way to use a remote template, maybe from a Github repo. Yes, you can!

How to create a Django project from a remote template

The --template flag for startproject accepts also an URL as the remote source. That means you can install a Django project from a remote template like so:

django-admin startproject --template https://github.com/username/repo/archive/master.zip new_django_project .

Bonus: template all the things

In addition to templating Django's related files, you can do the same thing for any other file in the project.

Imagine you want to deploy to Heroku, where a Procfile is needed. To pass the Procfile through the templating system so that {{ project_name }} is replaced by the actual project name you can run startproject with the --name flag:

django-admin startproject --template https://github.com/username/repo/archive/master.zip --name=Procfile new_django_project .

Make sure to have a placeholder for project_name in Procfile:

release: python manage.py migrate
web: gunicorn -w 3 {{ project_name }}.wsgi --log-file -

Resources

For a slighly complex Django template see ponee, a lightweight Django template ready for Heroku.

Originally published on my blog