Django Project Directory Structure

  • Published: July 16, 2016


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/
      • settings/
The preferred documentation format is reStructuredText .rst.
Keep virtual environment outside project $HOME/.virtualenvs//
_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.
comments powered by Disqus

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

Except as otherwise noted, the content of this page is licensed under CC BY-NC-ND 4.0 ·