Django UV Template

Minimal Django project using uv for blazingly fast Python package management.

Architecture

django_uv/
├── chats/              # Django app - business logic module
│   ├── migrations/     # Database schema changes
│   ├── models.py       # Data models
│   ├── views.py        # Request handlers
│   ├── admin.py        # Admin interface config
│   └── tests.py        # Unit tests
├── django_project/     # Django project - configuration hub
│   ├── settings.py     # Global settings
│   ├── urls.py         # URL routing
│   └── wsgi.py         # WSGI server interface
├── manage.py           # CLI entry point
└── db.sqlite3          # Local SQLite database

Philosophy

Django = Batteries Included

• ORM: No raw SQL unless necessary
• Admin: Auto-generated CRUD interface
• Migrations: Version control for database schema
• Apps: Reusable, loosely coupled modules

Quick Start

Prerequisites

• Python 3.12+
• uv package manager

Setup

# Install uv (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone <repo-url>
cd django_uv

# Install dependencies (uv reads pyproject.toml)
uv sync

# Run migrations
uv run python manage.py migrate

# Create superuser
uv run python manage.py createsuperuser

# Start dev server
uv run python manage.py runserver

Access at: http://127.0.0.1:8000

Development

Create New App

uv run python manage.py startapp <app_name>

# Add to INSTALLED_APPS in settings.py
INSTALLED_APPS = [
    # ...
    '<app_name>',
]

Database Operations

# Create migration after model changes
uv run python manage.py makemigrations

# Apply migrations
uv run python manage.py migrate

# View SQL for migrations
uv run python manage.py sqlmigrate <app_name> <migration_number>

Run Tests

uv run python manage.py test

Key Concepts

Model (Data Layer)

# chats/models.py
from django.db import models

class Message(models.Model):
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    
    class Meta:
        ordering = ['-created_at']

View (Logic Layer)

# chats/views.py
from django.shortcuts import render
from .models import Message

def message_list(request):
    messages = Message.objects.all()
    return render(request, 'chats/list.html', {'messages': messages})

URL Routing

# django_project/urls.py
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('chats/', include('chats.urls')),
]

Why uv?

• 10-100x faster than pip/poetry
• Rust-based resolver
• Single binary - no Python required for installation
• Compatible with pip/pyproject.toml

Project Structure Rules

1. One concern per app: Keep apps focused on single responsibility
2. No business logic in views: Use models/services
3. Migrations are immutable: Never edit applied migrations
4. Settings per environment: Use environment variables

Common Commands

# Shell with Django context
uv run python manage.py shell

# Database shell
uv run python manage.py dbshell

# Check for issues
uv run python manage.py check

# Collect static files (production)
uv run python manage.py collectstatic

Notes

• Development server reloads automatically on code changes
• SQLite is fine for development, use PostgreSQL in production
• Django admin is at /admin/ after creating superuser
• Timezone is UTC by default (change in settings.py)

Resources

• Django Documentation
• uv Documentation
• Django Best Practices