Django 2.x project template with a layout as a Python wheel.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

{% comment %}

Django Project Package Template

This is a template for a Django 2.x project.

The project has a layout so that it can be build as a wheel, one type of Python packages.


  • setup() is configured using a setup.cfg file.
  • The version is defined in {{ project_name }}.__version__.
  • Source code is located in a src directory to prevent side effects.
  • All apps use the {{ project_name }}.apps namespace.
  • All configuration modules use the {{ project_name }}.conf namespace.
  • {{ project_name }}.conf.settings uses pathlib instead of os and os.path.
  • Many settings can be defined using environment variables and parsed with envparse.
  • All templates, static files and locales will be included in the wheel.
  • All code follows the Black code style.
  • All docstrings follow PEP 257 conventions.
  • Django Debug Toolbar, IPython and check-manifest are already added to the development dependencies.
  • A Sublime Text project configuration is already included.


Use the following startproject command to create a new project using this template:

python3 -m django startproject --extension=cfg,gitignore,gitkeep,in,md,sublime-project \
    --template= \
    name [directory]

Tip: If you want to create the project in your current working directory use . as directory argument.


A testbed to quickly test the project template can be found in the separate django-project-package-template-testbed repository.


Distributed under the 3-Clause BSD License.

Copyright (c) 2018, Markus Zapke-Gründemann

All text below the horizontal line is the template for the new project's README.

{% endcomment %}# {{ project_name|title }}

Describe your project in one sentence.


Install the project and the development dependencies into a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install --editable .[dev]
./ migrate
./ runserver

Starting a New App

First create a new directory in the apps directory:

mkdir src/{{ project_name }}/apps/name

Then pass the path to the new directory to the [startapp]({{ docs_version }}/ref/django-admin/#django-admin-startapp) command:

./ startapp name src/{{ project_name }}/apps/name


The following list describes only the absolute necessary steps to outline a deployment for a Django project wheel. For example a component to serve static files is missing - you could use WhiteNoise to do this.

Also see [How to use Django with Gunicorn]({{ docs_version }}/howto/deployment/wsgi/gunicorn/) and [Deployment Checklist]({{ docs_version }}/howto/deployment/checklist/) for more information.

  1. Add your favorite WSGI HTTP server, e.g. Gunicorn, to install_requires in setup.cfg.
  2. Check if all files are included in the package:
  3. Build a wheel of the project.
    ./ bdist_wheel
  4. Copy the wheel file from the dist directory to the server to be deployed.
  5. Create a minimal configuration on the server using environment variables.
    export DJANGO_SETTINGS_MODULE={{ project_name }}.conf.settings
    export DJANGO_DEBUG=False
  6. Install the wheel and [collect the static files]({{ docs_version }}/ref/contrib/staticfiles/#django-admin-collectstatic):
    python3 -m pip install --find-links=/path/to/wheel_dir {{ project_name }}
    django-project collectstatic --no-input
  7. Start Gunicorn like this:
    gunicorn {{ project_name }}.wsgi