How to Setup Docker Compose in Django: The Ultimate Beginner's Guide (2025)

Running a Django project on your local machine is easy. But moving it to a colleague's laptop or a production server? That’s where the "It works on my machine" nightmares begin.

Docker solves this by packaging your code, database, and dependencies into a single, portable unit. Docker Compose takes it a step further by letting you run your Django app and your database (like PostgreSQL) with a single command.

In this guide, we will turn a standard Django project into a Dockerized super-app in 5 easy steps.

Prerequisites

Before we start, make sure you have:

1. Docker Desktop installed (download from docker.com).
2. A basic Django Project ready (or create one using django-admin startproject myproject).

Step 1: Create a requirements.txt

Docker needs to know which Python packages to install. If you haven't already, generate this file in your project's root folder.

pip freeze > requirements.txt

Make sure django and psycopg2-binary (for Postgres) are listed inside.

Step 2: The Dockerfile

A Dockerfile is like a recipe card that tells Docker how to build your Python environment. Create a file named Dockerfile (no extension) in your project root and paste this:

# 1. Use an official Python runtime as a parent image
FROM python:3.10-slim

# 2. Set environment variables
ENV PYTHONDONTWRITEBYTECODE 1
ENV PYTHONUNBUFFERED 1

# 3. Set the working directory in the container
WORKDIR /app

# 4. Install system dependencies (optional, but good for Postgres)
RUN apt-get update && apt-get install -y libpq-dev gcc

# 5. Install Python dependencies
COPY requirements.txt /app/
RUN pip install --upgrade pip
RUN pip install -r requirements.txt

# 6. Copy the project code into the container
COPY . /app/

Step 3: The docker-compose.yml file

This is the magic file. It orchestrates your Django app and your Database so they can talk to each other. Create a file named docker-compose.yml in your project root:

version: '3.8'
services:
 # Service 1: The Database
 db:
   image: postgres:15
   volumes:
     - postgres_data:/var/lib/postgresql/data
   environment:
     - POSTGRES_DB=myproject_db
     - POSTGRES_USER=myuser
     - POSTGRES_PASSWORD=mypassword
     
 # Service 2: The Django App
 web:
   build: .
   command: python manage.py runserver 0.0.0.0:8000
   volumes:
     - .:/app
   ports:
     - "8000:8000"
   environment:
     - DEBUG=1
     - SECRET_KEY=foo
     - DJANGO_ALLOWED_HOSTS=localhost 127.0.0.1 [::1]
   depends_on:
     - db
volumes:
 postgres_data:

What’s happening here?

• db: Pulls the official PostgreSQL image and sets up a default database user/password.
• web: Builds your Django app from the Dockerfile.
• depends_on: Tells Docker to start the database before starting the Django app.
• volumes: Maps your current folder (.) to the container folder (/app). This means if you change code on your laptop, it updates in the container instantly!

Step 4: Connect Django to Postgres

Now we need to tell Django to use this new Docker database instead of the default SQLite.

Open settings.py and modify the DATABASES section:

import os
DATABASES = {
   'default': {
       'ENGINE': 'django.db.backends.postgresql',
       'NAME': 'myproject_db',     # Must match POSTGRES_DB in docker-compose
       'USER': 'myuser',           # Must match POSTGRES_USER
       'PASSWORD': 'mypassword',   # Must match POSTGRES_PASSWORD
       'HOST': 'db',               # The name of the service in docker-compose
       'PORT': '5432',
   }
}

Step 5: Build and Run!

Open your terminal in the project folder and run:

docker-compose up --build

You will see a lot of text scrolling by as Docker builds your environment. Once it stops, open your browser and go to http://localhost:8000.

Wait, what about migrations? Since this is a fresh database, you need to create tables. In a new terminal tab, run:

docker-compose exec web python manage.py migrate

This command tells the "web" container to run the migrate command.

Common Commands You Need

• Stop everything: Ctrl + C or docker-compose down
• Rebuild after adding a new package: docker-compose up --build
• Create superuser: docker-compose exec web python manage.py createsuperuser

Conclusion

Congratulations! You have just containerized your Django application. No more installing Python versions manually or worrying about database conflicts. You can now share this project with anyone, and all they need to run it is docker-compose up.

Happy Coding!