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

1.2: Setting Up Your Django Project

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:

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:

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:

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

2. Install Dependencies:

3. Configure Settings:

Adjust environment variables or settings according to template documentation.

4. Run Initial Setup/Migrations:

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:

3. Configure Database in settings.py:

Update the DATABASES dictionary in settings.py:

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

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:

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

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:

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

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

1.2: Setting Up Your Django Project

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:

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:

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:

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

2. Install Dependencies:

3. Configure Settings:

Adjust environment variables or settings according to template documentation.

4. Run Initial Setup/Migrations:

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:

3. Configure Database in settings.py:

Update the DATABASES dictionary in settings.py:

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

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:

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

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:

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

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

Related Articles

Setting Up a Modern Spring Boot Web Server with REST API & Web Content (2025 Guide)

Related Bookmarks

Textual - Algorithms for high performance terminal apps

Related Projects

repo-tokens-calculator

aVenture.vc

SearchAI

Related Books

Build AI Applications with Spring AI

Advanced Algorithms and Data Structures

Just Use Postgres!

Related Investments

User Interviews

WeLoveNoCode

AngelList

Similar Content

Similar Content

Related Articles

Setting Up a Modern Spring Boot Web Server with REST API & Web Content (2025 Guide)

Related Bookmarks

Textual - Algorithms for high performance terminal apps

Related Projects

repo-tokens-calculator

aVenture.vc

SearchAI

Related Books

Build AI Applications with Spring AI

Advanced Algorithms and Data Structures

Just Use Postgres!

Related Investments

User Interviews

WeLoveNoCode

AngelList