Toggle dropdown

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).

Install and configure uv

uv is an extremely fast Python package installer and resolver, written in Rust. It's designed as a modern, high-performance alternative to tools like pip (the standard installer from PyPI, the Python Package Index) and Conda (a broader package and environment manager). uv aims to replace pip, pip-tools, and venv.

Installation Methods:

Important: Choose Only One Method

Select only one of the installation methods below. The official Astral install script (the first option) is generally preferred for most users.

Official Install Scripts (Cross-Platform - Preferred):
On macOS, Linux, and Windows (WSL/Git Bash/PowerShell):
curl -LsSf https://astral.sh/uv/install.sh | sh
Alternatively, for Windows PowerShell (if the above doesn't work directly):
irm https://astral.sh/uv/install.ps1 | iex
Homebrew (macOS/Linux):
brew install uv
Cargo (if you have Rust installed):
cargo install uv
pip (globally or in a pre-existing venv):
pip install uv

After installation, verify with: uv --version

For more details, see the

official uv installation guide.

Setup pip & venv

pip is the standard package installer for Python. venv is the standard module for creating lightweight virtual environments.

pip Installation/Upgrade:

pip is usually included with Python installations (version 3.4+). To ensure it's up-to-date:

python3 -m ensurepip --upgrade

Or, to upgrade an existing pip version:

python3 -m pip install --upgrade pip

Verify pip:

pip3 --version # or pip --version

venv Usage:

venv is part of the Python standard library (Python 3.3+). To create a virtual environment:

python3 -m venv .venv

Activate the virtual environment:

macOS/Linux (bash/zsh): source .venv/bin/activate
Windows (Command Prompt): .venv\Scripts\activate.bat
Windows (PowerShell): .venv\Scripts\Activate.ps1

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 --bare --python-pin
# `uv init` sets up the project for uv's dependency management, creating
# a minimal pyproject.toml and a .python-version file. This is where
# uv will track dependencies and can generate a uv.lock file for
# reproducible builds.

# 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`.

# 1. Create project directory and setup environment
mkdir my_django_project && cd my_django_project
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .\.venv\Scripts\activate

# 2. Install Django
pip install django

# 3. Verify installation
django-admin --version

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.

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

# Apply initial migrations
python 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
python 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

python manage.py createsuperuser

Follow prompts for username/password.

Setup VS Code for Django development

1. Install Extensions:

Python (Microsoft)
Pylance (Microsoft)
Django (Baptiste Darthenay) - Adds Django-specific features

2. Open Project & Configure:

Open your project folder in VS Code
Select Python interpreter from your virtual environment via Command Palette (Cmd+Shift+P / Ctrl+Shift+P) > "Python: Select Interpreter"
Use VS Code's integrated terminal to run Django commands

3. Run & Debug:

Use integrated terminal to run server with commands from Terminal tab
Configure .vscode/launch.json for debugging

Setup PyCharm for Django development

1. Create New Project:

Go to File > New Project
Select Django from the left panel
Configure location and environment (uv or Virtualenv)
PyCharm will create the project structure and virtual environment

If the project wizard (like in PyCharm) automatically sets up uv and a pyproject.toml file, you typically just need to run uv sync in the project directory to install the defined packages. After that, you can use uv run for all your commands (e.g., uv run manage.py migrate), as uv automatically handles the virtual environment activation.

PyCharm New Project dialog showing Django selected with 'uv' as the environment type — PyCharm's New Project wizard creating a default Django project.

2. Run & Manage:

Use the built-in "Django server" run configuration
Execute manage.py tasks via Terminal or Tools > Run manage.py Task...
Debug with the Debug button using the "Django server" configuration

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

python manage.py startapp my_first_app

App Naming Tip

When naming your Django app, it may be required to use lowercase alphabet-only characters and avoid special characters like underscores (e.g., avoid "my_first_app").

2. Register Your App:

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

INSTALLED_APPS = [
    # ... other apps
    'my_first_app', # Or 'my_first_app.apps.MyFirstAppConfig' if using AppConfig
    # ... django apps ...
]

3. Define a Simple Model:

Edit my_first_app/models.py:

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

# Generate migration files
python manage.py makemigrations my_first_app

# Apply migrations to database
python manage.py migrate

Create views and URL configuration

1. Create a View:

Edit my_first_app/views.py:

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><p>From my_first_app!</p>")

2. Create App URLs:

Create my_first_app/urls.py:

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):

from django.contrib import admin
from django.urls import path, include

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: Level Up with Modern Project Templates

Benefits of Modern Templates

These templates reduce boilerplate for common functionalities (auth, UI components, deployment setup), allowing you to focus on your unique 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: Less feature-rich.
Creative Tim / ThemeForest:
- Pros: Wide variety of 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

# Install cookiecutter if needed
pip install cookiecutter

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

# Clone directly from repository
git clone <repository_url> my_modern_project
cd my_modern_project

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.

# Install dependencies using Poetry
poetry install

# Install dependencies using PDM
pdm install

# Using uv with a new virtual environment
uv venv
uv pip install -r requirements.txt

# Or import into existing uv project
uv add -r requirements.txt

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .\.venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Build and start containers
docker-compose up --build

3. Configure Settings:

Adjust environment variables or settings according to template documentation.

4. Run Initial Setup/Migrations:

uv run manage.py migrate

python manage.py migrate

docker-compose exec web python manage.py migrate

Part 4: Implementing Core Admin Features with SQL Database

Core Admin Features in Django

Django offers robust 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

pip install psycopg2-binary

uv add mysqlclient

pip install mysqlclient

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',
    }
}

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

Database Credentials Tip

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

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 a powerful interface for managing your application's data.

1. Register Models in admin.py:

In your app's admin.py file:

from django.contrib import admin
from .models import Greeting

@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

# Start development server
python manage.py runserver

# Optional: specify port
python manage.py runserver 8080

# Create migrations based on model changes
uv run manage.py makemigrations

# Apply migrations to the database
uv run manage.py migrate

# Show migration status
uv run manage.py showmigrations

# Create migrations based on model changes
python manage.py makemigrations

# Apply migrations to the database
python manage.py migrate

# Show migration status
python manage.py showmigrations

# Create superuser (admin)
uv run manage.py createsuperuser

# Change user password
uv run manage.py changepassword username

# Create superuser (admin)
python manage.py createsuperuser

# Change user password
python manage.py changepassword username

# Start interactive Python shell with Django context
uv run manage.py shell

# Run tests
uv run manage.py test

# Run specific tests
uv run manage.py test app_name.tests.test_module

# Start interactive Python shell with Django context
python manage.py shell

# Run tests
python manage.py test

# Run specific tests
python manage.py test app_name.tests.test_module

# Collect static files to STATIC_ROOT
uv run manage.py collectstatic

# Find unused static files
uv run manage.py findstatic --first filename.ext

# Collect static files to STATIC_ROOT
python manage.py collectstatic

# Find unused static files
python manage.py findstatic --first filename.ext

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 a deeper dive into some deployment strategies and easy deployment options, I made a recent past 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:

# Find the process using port 8000
lsof -i :8000

# 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

# Install package
pip install <package_name>

# Verify installed packages
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

python manage.py shell

Example shell session for debugging models:

# Import your model
from my_first_app.models import Greeting

# Query data
Greeting.objects.all()

# Create test data
Greeting.objects.create(message="Hello, Django!")