Django Project Setup with uv and Docker

This guide provides a complete workflow for initializing, configuring, and containerizing a new Django project using modern tools like uv and Docker.

Step 1: Prerequisites

Ensure you have the following tools installed on your system:

• Python (3.8+ recommended)

• uv: A fast Python package installer and resolver. Install via curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or pipx install uv (Windows/cross-platform).

• Docker and Docker Compose: For containerizing the application.

• Visual Studio Code: With the Python extension installed.

• Git: For version control.

  
  

Step 2: Project & Virtual Environment Setup

First, we'll create the project directory and a dedicated virtual environment.

1. Create Project Directory: Open your terminal and create a root folder for your project.

   mkdir myproject
   cd myproject
   

2. Create and Activate Virtual Environment with uv: uv can create and manage virtual environments similarly to venv.

   uv init
   uv venv

   This creates a pyproject.toml file and a .venv directory automatically. 

   Now, activate it:

   • macOS / Linux:

     source .venv/bin/activate
     

   • Windows (PowerShell):

     .venv\Scripts\Activate.ps1

Step 3: Install Django & Create the Project

With the environment active, we'll install Django and create the project structure.

1. Install Django & Gunicorn: We will install Django for the project and Gunicorn as the production-ready web server.

   uv add django gunicorn

   This automatically installs Django and Gunicorn, updates pyproject.toml, and generates uv.lock for reproducible builds.

2. Create requirements.txt: It's best practice to freeze your dependencies into a requirements.txt file for reproducibility.

   uv export --format requirements-txt > requirements.txt

   Your requirements.txt will now contain Django, Gunicorn, and their dependencies.

3. Create the Django Project: Use django-admin to create the project. The . at the end places the manage.py file in the current directory, which is a common practice. Let's call the project core.

   uv run django-admin startproject core .

Your directory structure should now look like this:

myproject/
├── .venv/
├── core/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── manage.py
├── pyproject.toml
├── uv.lock
└── requirements.txt

Step 4: Git Initialization & .gitignore

Now, set up version control.

1. Initialize Git Repository:

   git init
   

2. Create a .gitignore file: Create a file named .gitignore in the root (myproject/) and add the following content to prevent committing unnecessary files like the virtual environment, IDE settings, and sensitive data.

   # Environments
   .venv/
   .env
   
   # Python
   __pycache__/
   *.pyc
   
   # Django
   *.log
   db.sqlite3
   db.sqlite3-journal
   media/
   static_collected/
   
   # IDEs / OS
   .vscode/
   .idea/
   .DS_Store
   

3. Make Your First Commit: Stage the files and create an initial commit.

   git add .
   git commit -m "Initial project structure with Django and .gitignore"
   

Step 5: Dockerization

Containerize the application for consistent development and deployment environments.

1. Create the Dockerfile: In the root directory (myproject/), create a file named Dockerfile.

   # myproject/Dockerfile
   FROM python:3.13-alpine
   ENV PYTHONDONTWRITEBYTECODE 1
   ENV PYTHONUNBUFFERED 1
   
   # Install uv
   RUN pip install uv
   
   # Create non-root user
   RUN addgroup --system app && adduser --system --group app
   
   WORKDIR /app
   
   # Copy uv project files first (for better caching)
   COPY pyproject.toml uv.lock ./
   
   # Install dependencies using uv's project management
   RUN uv sync --frozen --no-dev
   
   COPY . /app/
   
   EXPOSE 8000
   
   # Command for production
   CMD ["uv", "run", "gunicorn", "--bind", "0.0.0.0:8000", "core.wsgi:application"]

2. Create the docker-compose.yml file: In the root directory (myproject/), create docker-compose.yml. This file makes it easy to manage your container(s).

   # myproject/docker-compose.yml
   
   services:
     web:
       build: .
       command: python manage.py runserver 0.0.0.0:8000
       volumes:
         - .:/app
       ports:
         - "8000:8000"
   
   

Step 6: Running and Developing the Application

You can now run your project locally or with Docker.

1. Open in VS Code: From your project's root directory (myproject/), open it in VS Code.

   code .
   

   VS Code may prompt you to select a Python interpreter. Choose the one inside your .venv directory (.venv/bin/python).

2. Run with Django's Development Server (Local): For quick, local development, use the activated virtual environment.

   uv run python manage.py migrate
   uv run python manage.py runserver
   

3. Run with Docker Compose (Containerized): This is the recommended approach for a consistent environment.

   docker-compose up --build
   

   • The first time you run this, it will build the Docker image, which may take a minute.

   • Navigate to http://localhost:8000 in your browser.

   • To stop the containers, press Ctrl+C in the terminal, then run docker-compose down.

Your Django project is now fully set up for development with uv and Docker!