Contributing to Django is one thing, but how do you view your changes locally? That is what I asked the Djangonaut Space crew after making an HTML change to Django Admin. Let me share this discovery with you.

In this guide, I will show you how to create a Django project running on a local copy of Django Core using a simple setup (e.g., no Docker, Poetry, and all that).

This guide is not absolute: Feel free to do things your way or skip sections you already know. Experienced developers may want to skim through the headings and shell commands.

Important: All shell commands in this guide were tested with Zsh on macOS and should also work in Bash and Linux.

Why do we need two projects?

The Django Core package is not meant to be run stand-alone; it is a scaffold for your web project.

We will create a local (test) project similar to any other Django project. The only difference is that this test project will run on a local version of Django Core instead of the PyPI version.

Determining project location

Before getting started, find a place on your computer where you want to store the test project.

Ideally, for reasons we will get back to later, you want Django Core and your test project to be in the same directory, e.g., ~/Projects.

The project parent directory could look like this:

<user directory>
└── Projects

Setting up Django Core locally

Django already has an excellent guide that tells you all you need to know about creating a local, working copy of Django:

Writing your first patch for Django.

Follow the guide until "Running Django’s test suite for the first time" (I recommend running the tests once), and you should be ready!

The project parent directory could now look like this:

<user directory>
└── Projects
    └── django

Important: Do not forget to occasionally update your fork with the latest changes, pull them locally, and reinstall requirements!

Setting up a custom project

The local test project should be a bare minimum project for the sole purpose of running Django. You could easily create multiple projects, for example, one per ticket.

I will not use Git for this project since it only exists for local use.

Creating the project directory

First, we need a directory in which to store our project code. You can name it anything, but I chose django-local-test:

cd <path to project parent directory>
mkdir django-local-test

The project parent directory could now look like this:

<user directory>
└── Projects
    ├── django
    └── django-local-test

Navigate to the new directory:

cd django-local-test

Important: From now on, we will execute each command from this directory.

Creating a virtual environment

Next, we need a virtual environment (venv) to run our Python commands.

Note: Unlike the Django contributor guide, I prefer my virtual environments to be called venv and stored in the project directory. Feel free to use your preferred approach.

Create a venv:

python3.11 -m venv venv

…and activate it:

source venv/bin/activate

Important: You must run any Python command for the local project from this venv. If desired, you can create multiple command-line sessions, and you must activate the venv from each.

Installing the local Django Core in editable mode

We will use pip install -e <path to django> to install the local Django project in editable mode, meaning changes to the local Django Python files instantly persist to your running test project.

We will refer to the local Django by its paths relative to the test project root, which is ../django if both projects live in the same directory.

For reusability, we will store the installation path in a file called requirements.txt:

echo "-e ../django" >> requirements.txt

Now you can install the requirements from the file:

pip install -r requirements.txt

Writing project code

The time has come to create the Django code!

I will leave this step to you, as there are many ways to approach this. Pick whichever approach you like, for example:

• Follow the Django tutorial.
• Follow a third-party guide.
  • I like The Single Folder Django Project Layout by Carlton Gibson.
• Generate using a Cookiecutter project.
• Copy/paste from other projects. (At your own risk!)

Hint: Create only what you need. For example, I created a Model and matching ModelAdmin for a ticket requiring changes to Django Admin's HTML.

Running the code

If all went well, you should have created a runnable Django project.

Let us check using Django's built-in runserver command:

./<path to source>/manage.py runserver

Note: If you followed the Django tutorial, the value of <path to source> is probably mysite.

Seeing your changes

Any change you made to the Python code of the Django core project should show up in your project.

When using runserver, you should see a message from StatReloader in the output saying something like:

<path to file> changed, reloading.
Watching for file changes with StatReloader

You will notice that non-Python changes do not trigger an automatic reload. In that case, restart runserver to see these changes.

Profit!

You can now run a project with local modifications to Django Core. Have fun!