Buy me a coffeeBuy me a coffee

An approach on the most convenient way to organize directories for robust Django projects.


The structure that sets up Django by default is very basic, when a project starts to grow, it starts to require a better approach, that deals with other aspects of development and deployment such as:

  • deployment scripts
  • separated tests by units
  • having different environments for development, production (staging)
  • documentation for the project
  • $HOME/.virtualenvs/PROJECT_NAME
  • REPO-ROOT/ git repo
    • README.rst Summary of the project and how to install it
    • docs/
      • deployment.rst Step by step guide to deploy
      • installation.rst Setup for the project for other devs
      • architecture.rst How project evolves and what assumptions consider
    • .gitignore
    • requirements/
      • base.txt
      • local.txt
      • production.txt
      • test.txt
    • Makefile Deployment tasks
      • media/ only in development
      • static/ non user generated static media
      • templates/ site-wide
        • base.html
          • app-1/
          • app-2/
      • APP-1/
      • APP-2/
      • config/ CONFIGURATION-ROOT
        • settings/

The preferred documentation format is reStructuredText .rst.

Keep virtual environment outside project $HOME/.virtualenvs/<django_project_name>/

media directory should exists only in development, for user generated static media assets (e.g. photos).

assets (e.g. css) controlled by STATICFILES DIRS config variable. Media and static directories in production should be located in a static media server.

Two Scoops Of Django has the project structure they recommend implemented in the project Cookiecutter.


Marcelo Canina
I'm Marcelo Canina, a developer from Uruguay. I build websites and web-based applications from the ground up and share what I learn here.