How to Dockerize Your Django Project

If you’re working on a Django project and you want to make your life easier – especially when it comes to running your app across different environments – Docker is your new best friend.

Docker makes it possible to package your Django app, along with all its dependencies, into something called a “container.”

That way, it runs the same on your computer, your teammate’s computer, a testing server, or even in production.

When I first started using Docker, it felt a little overwhelming. But after setting it up for a few Django apps, it all clicked.

The good news? I’m going to walk you through it, step by step, in a way that’s easy to follow, even if you’re brand new to Docker.

Table of Contents

1. What You’ll Need

2. How to Dockerize Your Django Project

   • Step 1: Start a Django Project

   • Step 2: Create a Dockerfile

   • Step 3: Add a requirements.txt

   • Step 4: Create docker-compose.yml

   • Step 5: Run It!

3. Common Issues

   • Port Already in Use?

   • Database Not Working?

4. FAQs

   • Do I need Docker for development?

   • Can I run migrations inside Docker?

   • How do I stop everything?

5. Extra Tip: Use .dockerignore

6. What You’ve Built

7. Want to Go Deeper?

8. Further Reading

What You’ll Need

Before we begin, make sure you’ve got a few things installed:

• Python 3 (any version that Django supports)

• Django (of course)

• Docker and Docker Compose
  👉 Install Docker
  👉 Install Docker Compose

You don’t need to be an expert in Docker. I’ll explain what each part does as we build it together.

How to Dockerize Your Django Project

Step 1: Start a Django Project

If you already have a Django project, you can skip this part.

Otherwise, open your terminal and run:

django-admin startproject myproject
cd myproject

This will create a new Django project called myproject. You’ll see a structure like this:

myproject/
├── manage.py
└── myproject/
    ├── __init__.py
    ├── asgi.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py

Let’s say this is your app that you want to run inside Docker.

Step 2: Create a Dockerfile

In the root of your project (same folder as manage.py), create a file called Dockerfile. No file extension –just Dockerfile.

Here’s what goes inside:

# Use the official Python image
FROM python:3.10-slim

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

# Set the working directory in the container
WORKDIR /app

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

# Copy the rest of the code
COPY . /app/

Let me break that down:

• FROM python:3.10-slim: This tells Docker to use a lightweight version of Python 3.10.

• ENV: These just help with cleaner logs and better performance.

• WORKDIR /app: This sets the default working directory inside the container.

• COPY and RUN: These lines copy your code into the container and install your Python packages.

Step 3: Add a requirements.txt

You’ll need a file listing your Python packages.

Create a file called requirements.txt in the root folder and add:

Django>=4.0,<5.0

You can add more later if your project grows. For now, that’s enough.

To generate a full list of dependencies from your local virtual environment, run:

pip freeze > requirements.txt

Step 4: Create docker-compose.yml

Now let’s create the file that tells Docker how to run everything together.

In your root folder, create docker-compose.yml:

version: '3.9'

services:
  web:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"

Let’s go line-by-line:

• build: .: This tells Docker to use the Dockerfile in the current folder.

• command: This runs Django’s development server inside the container.

• volumes: This mounts your code into the container so changes are reflected live.

• ports: This maps port 8000 inside Docker to port 8000 on your machine.

So if you go to http://localhost:8000, you’ll see your app.

Step 5: Run It!

Now the fun part. From your terminal, run:

docker-compose up --build

This tells Docker to:

• Build the container

• Install dependencies

• Run the Django server

If everything goes well, you’ll see logs from the Django server, and you can open your browser and go to http://localhost:8000.

You should see the Django welcome screen.

Common Issues

Port Already in Use?

If port 8000 is busy, change this line in docker-compose.yml:

ports:
  - "8001:8000"

Then go to http://localhost:8001.

Database Not Working?

If you need a database (like PostgreSQL), you can add another service to docker-compose.yml. Here’s an example with PostgreSQL:

services:
  db:
    image: postgres
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
  web:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    depends_on:
      - db

Then, update your settings.py in Django to use that database.

FAQs

Do I need Docker for development?

No, but it helps keep your environment clean and consistent. If it works in Docker, it’ll work anywhere.

Can I run migrations inside Docker?

Yes! Just run:

docker-compose run web python manage.py migrate

How do I stop everything?

Press Ctrl+C to stop the running server, and if you want to remove containers:

docker-compose down

Extra Tip: Use .dockerignore

Just like .gitignore, you can create a .dockerignore file to avoid copying unnecessary files into the Docker container. Here’s a simple one:

__pycache__
*.pyc
*.pyo
*.pyd
.env
.git

What You’ve Built

By now, you’ve:

• Created a Django project

• Built a Docker container for it

• Set up docker-compose to run everything

• Learned how to manage it all easily

Once you’re comfortable, you can expand this setup with static files, NGINX, Gunicorn, or even production-ready Docker builds.

Want to Go Deeper?

If this feels like a lot, that’s ok. It takes a little practice, but once you’ve done it a few times, Docker becomes second nature.

You’ll spend less time debugging setup issues and more time coding your app.

Further Reading

• Docker Documentation

• Django Official Docs

• Compose File Reference

Source: freeCodeCamp Programming Tutorials: Python, JavaScript, Git & More