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

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

```bash 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: ```bash 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).

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:

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):
```bash curl -LsSf https://astral.sh/uv/install.sh | sh ```
Alternatively, for Windows PowerShell (if the above doesn't work directly):
```bash irm https://astral.sh/uv/install.ps1 | iex ```
Homebrew (macOS/Linux):{' '} ```bash brew install uv ```
Cargo (if you have Rust installed):{' '} ```bash cargo install uv ```
pip (globally or in a pre-existing venv):{' '} ```bash pip install uv ```

After installation, verify with: uv --version

For more details, see the{' '} official uv installation guide.

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:

```bash python3 -m ensurepip --upgrade ```

Or, to upgrade an existing pip version:

```bash python3 -m pip install --upgrade pip ```

Verify pip:

```bash pip3 --version # or pip --version ```

venv Usage:

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

```bash 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

```bash # 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`. ``` ```bash # 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 the project structure:

```bash # 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. ``` ```bash # 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):

```bash uv run manage.py createsuperuser ``` ```bash python manage.py createsuperuser ```

Follow prompts for username/password.

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

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.

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

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.

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:

```bash uv run manage.py startapp my_first_app ``` ```bash python manage.py startapp my_first_app ```

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

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

```bash # Generate migration files uv run manage.py makemigrations my_first_app # Apply migrations to database uv run manage.py migrate ```` ```bash # Generate migration files python manage.py makemigrations my_first_app # Apply migrations to database python manage.py migrate ```

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"

{greeting_text}

From my_first_app!

") ````

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

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 These templates reduce boilerplate for common functionalities (auth, UI components, deployment setup), so you can focus on your application logic.

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.

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

1. Generate or Clone the Template:

```bash # Install cookiecutter if needed uv add cookiecutter # Generate project from template uv run cookiecutter gh:cookiecutter/cookiecutter-django ```` ```bash # Install cookiecutter if needed pip install cookiecutter # Generate project from template cookiecutter gh:cookiecutter/cookiecutter-django ```

```bash # Clone directly from repository git clone my_modern_project cd my_modern_project ```

2. Install Dependencies:

```bash # 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. ``` ```bash # Install dependencies using Poetry poetry install ``` ```bash # Install dependencies using PDM pdm install ```

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

```bash # 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:

```bash uv run manage.py migrate ``` ```bash python manage.py migrate ``` ```bash docker-compose exec web python manage.py migrate ```

--- ## Part 4: Implementing Core Admin Features with SQL Database 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.

1. Choose a Database:

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

2. Install Database Drivers:

```bash uv add psycopg2-binary ``` ```bash pip install psycopg2-binary ```

```bash uv add mysqlclient ``` ```bash pip install mysqlclient ```

3. Configure Database in settings.py:

Update the DATABASES dictionary in settings.py:

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

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

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

```bash # Start development server uv run manage.py runserver # Optional: specify port uv run manage.py runserver 8080 ```` ```bash # Start development server python manage.py runserver # Optional: specify port python manage.py runserver 8080 ```

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

```bash # Create superuser (admin) uv run manage.py createsuperuser # Change user password uv run manage.py changepassword username ``` ```bash # Create superuser (admin) python manage.py createsuperuser # Change user password python manage.py changepassword username ```

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

```bash # Collect static files to STATIC_ROOT uv run manage.py collectstatic # Find unused static files uv run manage.py findstatic --first filename.ext ``` ```bash # 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 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

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 # Find the process using port 8000 lsof -i :8000 # Kill the process kill ````

"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 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

ModuleNotFoundError:

Ensure virtual environment is activated
Check if package is installed:

```bash # Install package uv add # Verify installed packages uv pip list ```` ```bash # Install package pip install # Verify installed packages pip list ```

Other Import Issues:

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

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:

```bash uv run manage.py shell ``` ```bash python manage.py shell ```

Example shell session for debugging models:

```python # Import your model from my_first_app.models import Greeting # Query data Greeting.objects.all() # Create test data Greeting.objects.create(message="Hello, Django!") ``` ```