Kickstarting a Modern Django Project (using UV) in 2025

Overview: Key Components & Their Roles

This guide covers setting up a modern Django project, including:

Django: A Python web framework for rapid development and clean design.
Modern Template: Using pre-built templates for a responsive UI/UX.
Core Admin Functionality: Implementing user authentication, admin panel, and core product models.
SQL Database Integration (PostgreSQL/MySQL): Connecting Django to a relational database.
IDE Tooling (VSCode/IntelliJ IDEA): Optimizing development with extensions and configurations.
Fast-Start Resources: Libraries and communities to accelerate development.

Part 1: Setting Up Your Initial Django Project

This part covers setting up a standard, default Django project using your preferred workflow (Terminal, VS Code, or PyCharm).

1.1: Getting Started: Prerequisites & Setup

Ensure Python 3 is installed

You'll need Python 3 (ideally a recent version like 3.8 or newer). Check if Python is installed:

python3 --version

If not installed, or you need a different version:

Official Website: Download from python.org.
Alternative for macOS (and Linux) - Homebrew:
Use the following command:
brew install python3
Linux: Use your distribution's package manager (e.g., sudo apt update && sudo apt install python3 for Debian/Ubuntu).
Windows: Install from the Microsoft Store or python.org. Consider using Windows Subsystem for Linux (WSL).

1.2: Setting Up Your Django Project

Create project & install Django

# 1. Create project directory and setup environment
mkdir my_django_project && cd my_django_project
uv venv
# `uv venv` creates a lightweight virtual environment in the .venv directory,
# isolating project dependencies from the system Python installation.
# For more details on how uv manages Python environments, see the official documentation: https://docs.astral.sh/uv/pip/environments/
uv init --python 3.12
# `uv init` creates a `pyproject.toml` in the current directory and pins the
# requested Python version. The command also prepares the environment so `uv`
# can manage dependencies and generate a reproducible `uv.lock` file.

# 2. Install Django
uv add django
# `uv add` installs the specified package (Django) and automatically
# updates pyproject.toml and uv.lock to reflect the new dependency
# and its exact version and dependencies.

# 3. Verify installation
uv run django-admin --version
# `uv run` executes a command within the project's virtual environment.
# This means you don't need to explicitly activate the environment
# with `source .venv/bin/activate` (or similar) every time you open a new terminal,
# unlike common workflows with `pip` and `venv`.

Create Django project files & run server

Create the project structure:

# Create project files (replace "config" with preferred name)
uv run django-admin startproject config .

# Apply initial migrations
uv run manage.py migrate
# This command applies database migrations, setting up the necessary tables.
# By default, Django uses an SQLite database stored in a file named db.sqlite3
# in your project's root directory if no other database is configured.

# Run development server
uv run manage.py runserver
# This starts Django's built-in development web server.

Access at http://127.0.0.1:8000/. Stop server with Ctrl+C.

Create Superuser (Optional but recommended):

uv run manage.py createsuperuser

Follow prompts for username/password.

Next Steps

Now that you have a basic Django project running using your preferred setup method, the next sections will cover creating your first app and using modern project templates.

Part 2: Adding Your First App & Core Concepts

A Django project is the overall container for your application's settings and configurations (e.g., database settings, installed apps, URL routing at the project level). A project can contain multiple apps, which are modular components that handle specific functionalities (like a blog, a user management system, etc.). Think of the project as the building and apps as the distinct rooms or services within it.

With the default project running, let's create your first Django app and understand core concepts.

Create your first app & configure

Django projects are composed of one or more "apps." An app is a self-contained module that handles a specific piece of functionality.

1. Create the App:

uv run manage.py startapp my_first_app

App naming tip

App labels need to be valid Python identifiers. Stick to lowercase letters and optional underscores (for example, my_first_app) so the generated package imports cleanly.

2. Register Your App:

Add your new app to INSTALLED_APPS in your project's settings.py file:

python

'my_first_app.apps.MyFirstAppConfig' if using AppConfig # ... django apps ... ] ```

<div className="py-[6px]">
  <strong>3. Define a Simple Model:</strong>
</div>
<div>
  Edit <code>my_first_app/models.py</code>:
</div>
```python from django.db import models

class Greeting(models.Model):
message = models.CharField(max_length=255)
created_at = models.DateTimeField(auto_now_add=True)

      def __str__(self):
          return self.message

4. Create & Apply Migrations:

# Generate migration files
uv run manage.py makemigrations my_first_app

# Apply migrations to database
uv run manage.py migrate

Create views and URL configuration

1. Create a View:

Edit my_first_app/views.py:

python

from django.http import HttpResponse
from .models import Greeting

def hello_world(request):
greeting = Greeting.objects.first() # Get the first greeting, or None
if not greeting:
greeting_text = "No greetings yet!"
else:
greeting_text = greeting.message
return HttpResponse(f"<h1>{greeting_text}</h1><div>From my_first_app!</div>")

2. Create App URLs:

Create my_first_app/urls.py:

python

from django.urls import path
from . import views

urlpatterns = [
    path('hello/', views.hello_world, name='hello_world'),
]

3. Include in Project URLs:

Update your project's urls.py (e.g., config/urls.py):

python


urlpatterns = [
path('admin/', admin.site.urls),
path('app/', include('my_first_app.urls')), # This adds your app URLs
]

Now visit http://127.0.0.1:8000/app/hello/ to see your view in action.

Key Django concepts

Apps for Features: Organize functionality into reusable, modular apps
MVT (Model-View-Template): Django's architecture pattern
- Models - Define data structure and interact with database
- Views - Handle logic and request/response flow
- Templates - Present information to users (HTML)
URL Routing: Map web addresses to view functions
Admin Interface: Built-in data management UI
ORM: Object-Relational Mapper for database operations using Python

Part 3: Modern Project Templates

Benefits of Modern Templates

These templates reduce boilerplate for common functionalities (auth, UI components, deployment setup), so you can focus on your application logic.

Popular modern template options

Cookiecutter Django:
- Pros: Highly configurable, production-ready (Docker, Celery), many best practices.
- Cons: Can be complex for beginners.
SaaS Pegasus:
- Pros: For SaaS apps; includes subscriptions, teams, pre-built UI. Good documentation.
- Cons: Paid.
DjangoX:
- Pros: Simpler starter; Tailwind CSS, user auth.
- Cons: Fewer features.
Creative Tim / ThemeForest:
- Pros: Many themes.
- Cons: Quality and Django integration vary.

Setting up a modern template

Most templates provide detailed setup instructions, but here's a general workflow:

1. Generate or Clone the Template:

# Install cookiecutter if needed
uv add cookiecutter

# Generate project from template
uv run cookiecutter gh:cookiecutter/cookiecutter-django

2. Install Dependencies:

# Sync dependencies using uv
uv sync
# `uv sync` installs the exact dependencies specified in the uv.lock file,
# ensuring that everyone working on the project has the same environment.

3. Configure Settings:

Adjust environment variables or settings according to template documentation.

4. Run Initial Setup/Migrations:

uv run manage.py migrate

Part 4: Implementing Core Admin Features with SQL Database

Core Admin Features in Django

Django has built-in features for web applications: - User Authentication: django.contrib.auth for user management. - Admin Panel: django.contrib.admin for data management. - ORM & Models: Django's ORM for database interaction via Python.

Setting up SQL database

1. Choose a Database:

PostgreSQL or MySQL are recommended for production. SQLite (default) works for development.

2. Install Database Drivers:

uv add psycopg2-binary

3. Configure Database in settings.py:

Update the DATABASES dictionary in settings.py:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydatabase',
        'USER': 'mydatabaseuser',
        'PASSWORD': 'mypassword',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    }
}

Database Credentials Tip

For production, use environment variables for database credentials, not hardcoded values:

python

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME', 'mydatabase'),
        'USER': os.environ.get('DB_USER', 'mydatabaseuser'),
        'PASSWORD': os.environ.get('DB_PASSWORD', 'mypassword'),
        'HOST': os.environ.get('DB_HOST', '127.0.0.1'),
        'PORT': os.environ.get('DB_PORT', '5432'),
    }
}

Admin panel configuration

Django's admin panel provides an interface for managing your application's data.

1. Register Models in admin.py:

In your app's admin.py file:

python


@admin.register(Greeting)
class GreetingAdmin(admin.ModelAdmin):
list_display = ('message', 'created_at')
search_fields = ('message',)

2. Access Admin Interface:

After starting the development server, visit http://127.0.0.1:8000/admin/ and log in with superuser credentials.

Admin Customization Options:

list_display: Fields to show in list view
search_fields: Fields to search through
list_filter: Enable filtering by fields
fieldsets: Organize fields in detail view
readonly_fields: Fields that can't be edited

Part 5: Essential Django Commands

Execute from project root with virtual environment active.

# Start development server
uv run manage.py runserver

# Optional: specify port
uv run manage.py runserver 8080

Beyond Development: Deployment Considerations

While this guide focuses on setting up your local development environment, deploying your Django application to a production server involves additional steps. Unlike the built-in development server, production deployments typically use a Web Server Gateway Interface (WSGI) server (like Gunicorn or uWSGI) to handle requests, often in conjunction with a web proxy server (like Nginx or Apache, or AWS Lambda).

For more on deployment strategies and options, I made a recent post sharing my current hosting preferences: How I Host My Apps: How to Deploy in 2025

Part 6: Troubleshooting Common Issues

Development server issues

Stopping the Server:

Clean Stop: Ctrl+C in the terminal
If Ctrl+Z was used: Use fg then Ctrl+C, or jobs and kill %JOB_NUMBER

Address Already in Use:

If you see "Address already in use," find and kill the process:

bash


# Kill the process

kill <PID>

Migration issues

"No changes detected":

Check that your app is in INSTALLED_APPS
Verify you saved all changes to models.py
Ensure you're specifying the correct app name in the command

Migration Errors:

Verify database connection settings
Check for syntax errors in models
View migration status with python manage.py showmigrations

Static files & templates

Static Files Not Loading (404s):

Development: Check STATIC_URL, ensure files are in app_name/static/app_name/
Production: Run collectstatic, configure web server for STATIC_ROOT

TemplateDoesNotExist Error:

Verify app is in INSTALLED_APPS
Check template path - should be in app_name/templates/app_name/
Check for typos in template names

Import & package issues

ModuleNotFoundError:

Ensure virtual environment is activated
Check if package is installed:

# Install package
uv add <package_name>

# Verify installed packages
uv pip list

Other Import Issues:

Check for typos in import statements
Verify proper Python package structure
Beware of circular imports

Database debugging

Connection Problems:

Verify database settings in settings.py
Ensure database server is running
Check firewall settings
Confirm correct driver is installed

Using Django Shell for Debugging:

uv run manage.py shell

Example shell session for debugging models:

python


# Query data

Greeting.objects.all()

# Create test data

Greeting.objects.create(message="Hello, Django!")

Overview: Key Components & Their Roles

This guide covers setting up a modern Django project, including:

Django: A Python web framework for rapid development and clean design.
Modern Template: Using pre-built templates for a responsive UI/UX.
Core Admin Functionality: Implementing user authentication, admin panel, and core product models.
SQL Database Integration (PostgreSQL/MySQL): Connecting Django to a relational database.
IDE Tooling (VSCode/IntelliJ IDEA): Optimizing development with extensions and configurations.
Fast-Start Resources: Libraries and communities to accelerate development.

Part 1: Setting Up Your Initial Django Project

This part covers setting up a standard, default Django project using your preferred workflow (Terminal, VS Code, or PyCharm).

1.1: Getting Started: Prerequisites & Setup

Ensure Python 3 is installed

You'll need Python 3 (ideally a recent version like 3.8 or newer). Check if Python is installed:

python3 --version

If not installed, or you need a different version:

Official Website: Download from python.org.
Alternative for macOS (and Linux) - Homebrew:
Use the following command:
brew install python3
Linux: Use your distribution's package manager (e.g., sudo apt update && sudo apt install python3 for Debian/Ubuntu).
Windows: Install from the Microsoft Store or python.org. Consider using Windows Subsystem for Linux (WSL).

1.2: Setting Up Your Django Project

Create project & install Django

# 1. Create project directory and setup environment
mkdir my_django_project && cd my_django_project
uv venv
# `uv venv` creates a lightweight virtual environment in the .venv directory,
# isolating project dependencies from the system Python installation.
# For more details on how uv manages Python environments, see the official documentation: https://docs.astral.sh/uv/pip/environments/
uv init --python 3.12
# `uv init` creates a `pyproject.toml` in the current directory and pins the
# requested Python version. The command also prepares the environment so `uv`
# can manage dependencies and generate a reproducible `uv.lock` file.

# 2. Install Django
uv add django
# `uv add` installs the specified package (Django) and automatically
# updates pyproject.toml and uv.lock to reflect the new dependency
# and its exact version and dependencies.

# 3. Verify installation
uv run django-admin --version
# `uv run` executes a command within the project's virtual environment.
# This means you don't need to explicitly activate the environment
# with `source .venv/bin/activate` (or similar) every time you open a new terminal,
# unlike common workflows with `pip` and `venv`.

Create Django project files & run server

Create the project structure:

# Create project files (replace "config" with preferred name)
uv run django-admin startproject config .

# Apply initial migrations
uv run manage.py migrate
# This command applies database migrations, setting up the necessary tables.
# By default, Django uses an SQLite database stored in a file named db.sqlite3
# in your project's root directory if no other database is configured.

# Run development server
uv run manage.py runserver
# This starts Django's built-in development web server.

Access at http://127.0.0.1:8000/. Stop server with Ctrl+C.

Create Superuser (Optional but recommended):

uv run manage.py createsuperuser

Follow prompts for username/password.

Next Steps

Now that you have a basic Django project running using your preferred setup method, the next sections will cover creating your first app and using modern project templates.

Part 2: Adding Your First App & Core Concepts

With the default project running, let's create your first Django app and understand core concepts.

Create your first app & configure

Django projects are composed of one or more "apps." An app is a self-contained module that handles a specific piece of functionality.

1. Create the App:

uv run manage.py startapp my_first_app

App naming tip

App labels need to be valid Python identifiers. Stick to lowercase letters and optional underscores (for example, my_first_app) so the generated package imports cleanly.

2. Register Your App:

Add your new app to INSTALLED_APPS in your project's settings.py file:

python

'my_first_app.apps.MyFirstAppConfig' if using AppConfig # ... django apps ... ] ```

<div className="py-[6px]">
  <strong>3. Define a Simple Model:</strong>
</div>
<div>
  Edit <code>my_first_app/models.py</code>:
</div>
```python from django.db import models

class Greeting(models.Model):
message = models.CharField(max_length=255)
created_at = models.DateTimeField(auto_now_add=True)

      def __str__(self):
          return self.message

4. Create & Apply Migrations:

# Generate migration files
uv run manage.py makemigrations my_first_app

# Apply migrations to database
uv run manage.py migrate

Create views and URL configuration

1. Create a View:

Edit my_first_app/views.py:

python

from django.http import HttpResponse
from .models import Greeting

def hello_world(request):
greeting = Greeting.objects.first() # Get the first greeting, or None
if not greeting:
greeting_text = "No greetings yet!"
else:
greeting_text = greeting.message
return HttpResponse(f"<h1>{greeting_text}</h1><div>From my_first_app!</div>")

2. Create App URLs:

Create my_first_app/urls.py:

python

from django.urls import path
from . import views

urlpatterns = [
    path('hello/', views.hello_world, name='hello_world'),
]

3. Include in Project URLs:

Update your project's urls.py (e.g., config/urls.py):

python


urlpatterns = [
path('admin/', admin.site.urls),
path('app/', include('my_first_app.urls')), # This adds your app URLs
]

Now visit http://127.0.0.1:8000/app/hello/ to see your view in action.

Key Django concepts

Apps for Features: Organize functionality into reusable, modular apps
MVT (Model-View-Template): Django's architecture pattern
- Models - Define data structure and interact with database
- Views - Handle logic and request/response flow
- Templates - Present information to users (HTML)
URL Routing: Map web addresses to view functions
Admin Interface: Built-in data management UI
ORM: Object-Relational Mapper for database operations using Python

Part 3: Modern Project Templates

Benefits of Modern Templates

These templates reduce boilerplate for common functionalities (auth, UI components, deployment setup), so you can focus on your application logic.

Popular modern template options

Cookiecutter Django:
- Pros: Highly configurable, production-ready (Docker, Celery), many best practices.
- Cons: Can be complex for beginners.
SaaS Pegasus:
- Pros: For SaaS apps; includes subscriptions, teams, pre-built UI. Good documentation.
- Cons: Paid.
DjangoX:
- Pros: Simpler starter; Tailwind CSS, user auth.
- Cons: Fewer features.
Creative Tim / ThemeForest:
- Pros: Many themes.
- Cons: Quality and Django integration vary.

Setting up a modern template

Most templates provide detailed setup instructions, but here's a general workflow:

1. Generate or Clone the Template:

# Install cookiecutter if needed
uv add cookiecutter

# Generate project from template
uv run cookiecutter gh:cookiecutter/cookiecutter-django

2. Install Dependencies:

# Sync dependencies using uv
uv sync
# `uv sync` installs the exact dependencies specified in the uv.lock file,
# ensuring that everyone working on the project has the same environment.

3. Configure Settings:

Adjust environment variables or settings according to template documentation.

4. Run Initial Setup/Migrations:

uv run manage.py migrate

Part 4: Implementing Core Admin Features with SQL Database

Core Admin Features in Django

Setting up SQL database

1. Choose a Database:

PostgreSQL or MySQL are recommended for production. SQLite (default) works for development.

2. Install Database Drivers:

uv add psycopg2-binary

3. Configure Database in settings.py:

Update the DATABASES dictionary in settings.py:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydatabase',
        'USER': 'mydatabaseuser',
        'PASSWORD': 'mypassword',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    }
}

Database Credentials Tip

For production, use environment variables for database credentials, not hardcoded values:

python

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME', 'mydatabase'),
        'USER': os.environ.get('DB_USER', 'mydatabaseuser'),
        'PASSWORD': os.environ.get('DB_PASSWORD', 'mypassword'),
        'HOST': os.environ.get('DB_HOST', '127.0.0.1'),
        'PORT': os.environ.get('DB_PORT', '5432'),
    }
}

Admin panel configuration

Django's admin panel provides an interface for managing your application's data.

1. Register Models in admin.py:

In your app's admin.py file:

python


@admin.register(Greeting)
class GreetingAdmin(admin.ModelAdmin):
list_display = ('message', 'created_at')
search_fields = ('message',)

2. Access Admin Interface:

After starting the development server, visit http://127.0.0.1:8000/admin/ and log in with superuser credentials.

Admin Customization Options:

list_display: Fields to show in list view
search_fields: Fields to search through
list_filter: Enable filtering by fields
fieldsets: Organize fields in detail view
readonly_fields: Fields that can't be edited

Part 5: Essential Django Commands

Execute from project root with virtual environment active.

# Start development server
uv run manage.py runserver

# Optional: specify port
uv run manage.py runserver 8080

Beyond Development: Deployment Considerations

For more on deployment strategies and options, I made a recent post sharing my current hosting preferences: How I Host My Apps: How to Deploy in 2025

Part 6: Troubleshooting Common Issues

Development server issues

Stopping the Server:

Clean Stop: Ctrl+C in the terminal
If Ctrl+Z was used: Use fg then Ctrl+C, or jobs and kill %JOB_NUMBER

Address Already in Use:

If you see "Address already in use," find and kill the process:

bash


# Kill the process

kill <PID>

Migration issues

"No changes detected":

Check that your app is in INSTALLED_APPS
Verify you saved all changes to models.py
Ensure you're specifying the correct app name in the command

Migration Errors:

Verify database connection settings
Check for syntax errors in models
View migration status with python manage.py showmigrations

Static files & templates

Static Files Not Loading (404s):

Development: Check STATIC_URL, ensure files are in app_name/static/app_name/
Production: Run collectstatic, configure web server for STATIC_ROOT

TemplateDoesNotExist Error:

Verify app is in INSTALLED_APPS
Check template path - should be in app_name/templates/app_name/
Check for typos in template names

Import & package issues

ModuleNotFoundError:

Ensure virtual environment is activated
Check if package is installed:

# Install package
uv add <package_name>

# Verify installed packages
uv pip list

Other Import Issues:

Check for typos in import statements
Verify proper Python package structure
Beware of circular imports

Database debugging

Connection Problems:

Verify database settings in settings.py
Ensure database server is running
Check firewall settings
Confirm correct driver is installed

Using Django Shell for Debugging:

uv run manage.py shell

Example shell session for debugging models:

python


# Query data

Greeting.objects.all()

# Create test data

Greeting.objects.create(message="Hello, Django!")

Overview: Key Components & Their Roles

Part 1: Setting Up Your Initial Django Project

1.1: Getting Started: Prerequisites & Setup

1.2: Setting Up Your Django Project

Next Steps

Part 2: Adding Your First App & Core Concepts

App naming tip

Part 3: Modern Project Templates

Benefits of Modern Templates

Part 4: Implementing Core Admin Features with SQL Database

Core Admin Features in Django

Database Credentials Tip

Part 5: Essential Django Commands

Beyond Development: Deployment Considerations

Part 6: Troubleshooting Common Issues

Similar Content

Overview: Key Components & Their Roles

Part 1: Setting Up Your Initial Django Project

1.1: Getting Started: Prerequisites & Setup

1.2: Setting Up Your Django Project

Next Steps

Part 2: Adding Your First App & Core Concepts

App naming tip

Part 3: Modern Project Templates

Benefits of Modern Templates

Part 4: Implementing Core Admin Features with SQL Database

Core Admin Features in Django

Database Credentials Tip

Part 5: Essential Django Commands

Beyond Development: Deployment Considerations

Part 6: Troubleshooting Common Issues

Similar Content