Introduction
When you create your first Django project, you may see several files and folders appear automatically.
At first, the structure can look confusing:
myproject/
├── manage.py
├── myproject/
│ ├── __init__.py
│ ├── settings.py
│ ├── urls.py
│ ├── asgi.py
│ └── wsgi.py
If you’re new to Django, you might wonder:
- What does
manage.pydo? - What is
settings.pyused for? - Where should database logic go?
- What is the difference between a project and an app?
- Where should templates and CSS files be stored?
- Where should Views and models be created?
Understanding the Django project structure is one of the first important steps toward becoming comfortable with Django.
In this guide, we’ll break down the Django folder structure in simple terms and explain what each important file and directory is responsible for.
What Is a Django Project?
A Django project is the overall configuration and foundation of a Django-powered website or application.
It usually contains:
- Project configuration
- Settings
- URL configuration
- Application configuration
- Server configuration
- Installed Django apps
For example, an online learning platform might be one Django project containing multiple applications.
Education Platform
│
├── Accounts
├── Courses
├── Payments
├── Notifications
└── Reviews
The project acts as the main container for these applications.
What Is a Django App?
A Django app is a smaller component of a Django project that focuses on a particular feature or area of functionality.
For example, a project could contain:
accountsproductsordersblogpayments
Each app can have its own:
- Models
- Views
- URLs
- Forms
- Templates
- Tests
- Business logic
A useful way to think about it is:
Django Project = Entire Website/Application
Django App = Individual Feature or Module
Django Project vs Django App
This distinction is extremely important for beginners.
Imagine you’re building an e-commerce website.
The complete website is the Django project.
Inside it, you could have:
E-commerce Project
│
├── users app
├── products app
├── orders app
├── payments app
└── reviews app
The project provides the overall configuration, while each app handles a specific part of the application.
Typical Django Project Structure
A basic Django project might look like this:
myproject/
│
├── manage.py
│
├── myproject/
│ ├── __init__.py
│ ├── settings.py
│ ├── urls.py
│ ├── asgi.py
│ └── wsgi.py
│
└── blog/
├── __init__.py
├── admin.py
├── apps.py
├── models.py
├── tests.py
├── views.py
└── migrations/
└── __init__.py
As your project grows, you may also add:
templates/
static/
media/
forms.py
services/
serializers.py
The exact structure can vary depending on the project’s size and architecture.
Understanding manage.py
manage.py is one of the most important files in a Django project.
It provides a command-line interface for interacting with your Django project.
Developers commonly use it for tasks such as:
- Running the development server
- Creating migrations
- Applying migrations
- Creating Django apps
- Creating superusers
- Running tests
- Opening the Django shell
- Collecting static files
For example, commands such as:
python manage.py runserver
and:
python manage.py migrate
use manage.py.
You can think of it as the main command-line entry point for managing a Django project.
What Is init.py?
You may notice a file called:
__init__.py
inside Django project and app directories.
This file indicates that the directory is a Python package.
It also allows Python to treat the directory as an importable package.
In many modern Python versions, some package behavior can work without an __init__.py, but Django projects commonly include it as part of the standard structure.
For beginners, the important point is:
Don’t delete it without understanding the consequences.
Understanding settings.py
settings.py contains the configuration for your Django project.
It is one of the most important files in the entire project.
Common settings include:
- Installed applications
- Middleware
- Database configuration
- Templates
- Static files
- Media files
- Time zone
- Language
- Security settings
- Authentication settings
- Allowed hosts
For example, when you install a new Django app, you typically need to add it to the project’s installed applications.
Installed Apps
Django projects use the INSTALLED_APPS configuration to identify which applications are enabled.
This can include:
- Django’s built-in applications
- Third-party applications
- Your own custom applications
For example:
Django Project
│
├── Authentication
├── Admin
├── Blog
├── Products
└── Payments
The installed apps configuration tells Django which applications should be loaded.
Database Configuration
The Django database configuration is also located in settings.py.
A development project might use SQLite.
Production applications may use databases such as:
- PostgreSQL
- MySQL
- MariaDB
The database configuration tells Django how to connect to the application’s database.
Templates Configuration
Django uses templates to generate HTML pages.
The template configuration in settings.py tells Django where it should look for templates and how templates should be processed.
A common structure is:
templates/
├── base.html
├── home.html
└── blog/
└── post.html
Templates are generally responsible for the presentation layer of a traditional Django application.
Static Files
Static files are files such as:
- CSS
- JavaScript
- Icons
- Website images
- Fonts
A project may organize them using a structure such as:
static/
├── css/
├── js/
└── images/
Django provides a static files system to help manage these assets.
For production deployments, static files are commonly collected and served through a web server or CDN.
Media Files
Media files are different from static files.
Static Files
Files provided by the application.
Examples:
- CSS
- JavaScript
- Website logos
Media Files
Files uploaded by users.
Examples:
- Profile pictures
- Product images
- Documents
- User attachments
A common structure is:
media/
├── profiles/
├── products/
└── documents/
Django provides settings such as MEDIA_ROOT and MEDIA_URL for handling uploaded files.
Understanding urls.py
The urls.py file defines URL patterns for the project.
It tells Django which part of the application should handle a particular URL.
For example:
/blog/
might be connected to a blog application.
While:
/accounts/
might be connected to an authentication application.
A large project often separates URL configurations between the project and individual apps.
Project URLs vs App URLs
This is another important Django concept.
The main project can contain the primary URL configuration:
myproject/urls.py
An individual app can also have its own:
blog/urls.py
The project-level URL configuration can connect requests to the appropriate app.
For example:
Website
│
├── /accounts/ → Accounts App
├── /blog/ → Blog App
├── /products/ → Products App
└── /orders/ → Orders App
This keeps URL configurations organized as the application grows.
Understanding views.py
views.py contains the code responsible for handling requests and returning responses.
A View can:
- Receive a request
- Retrieve data
- Validate information
- Perform application logic
- Render a template
- Return JSON
- Redirect users
- Return an HTTP response
For example, a blog View might:
- Receive a request.
- Retrieve a blog post.
- Pass the post to a template.
- Return the rendered page.
Function-Based Views
Django supports function-based Views.
These are Python functions that receive a request and return a response.
They can be simple and easy to understand, especially for beginners.
Function-based Views are useful for straightforward request handling.
Class-Based Views
Django also provides class-based Views.
Class-based Views can be useful when you want to organize reusable behavior or take advantage of Django’s generic Views.
They are commonly used for:
- List pages
- Detail pages
- Create forms
- Update forms
- Delete operations
Choosing between function-based and class-based Views depends on the application and developer preference.
Understanding models.py
models.py contains the database models for a Django app.
A model represents data that your application needs to store.
For example, a blog application might have:
Post
- Title
- Content
- Author
- Published date
- Image
An e-commerce application might have:
Product
- Name
- Price
- Description
- Category
- Image
Django models are converted into database structures through migrations.
Django ORM and Models
Django includes its own Object-Relational Mapping system, commonly called the Django ORM.
The ORM allows developers to work with database data using Python objects and querysets instead of writing SQL for every operation.
For example, you can use Django models to:
- Create records
- Retrieve records
- Update records
- Delete records
- Filter data
- Work with relationships
This is one of Django’s most powerful features.
Understanding migrations
Django apps usually contain a migrations directory.
It may look like:
migrations/
├── __init__.py
├── 0001_initial.py
└── 0002_add_category.py
Migrations track changes made to your Django models.
For example:
Model changes
↓
Migration created
↓
Migration applied
↓
Database structure updated
Migrations allow Django to manage database schema changes in a structured way.
What Is admin.py?
admin.py is used to configure models for Django’s built-in admin interface.
The Django admin panel provides a convenient interface for managing application data.
For example, you can register models such as:
- Users
- Products
- Blog posts
- Categories
- Orders
Once registered and configured, these models can be managed through the Django admin interface.
What Is apps.py?
apps.py contains the configuration for a Django application.
It usually contains an application configuration class.
This file can be used for app-level configuration and initialization.
For example, it is commonly involved when configuring certain application startup behavior, including loading signal handlers.
What Is tests.py?
tests.py is where Django applications can contain automated tests.
Tests help verify that your application works as expected.
You might test:
- Models
- Views
- Forms
- APIs
- Authentication
- Business logic
As applications become larger, developers may organize tests into a dedicated tests/ package rather than keeping everything in a single tests.py file.
What Are asgi.py and wsgi.py?
Django projects commonly include two server gateway files:
wsgi.pyasgi.py
These files are related to deploying and serving Django applications.
What Is WSGI?
WSGI stands for Web Server Gateway Interface.
It provides a standard interface between Python web applications and compatible web servers.
WSGI has traditionally been widely used for deploying Django applications.
It is suitable for traditional synchronous Django applications.
What Is ASGI?
ASGI stands for Asynchronous Server Gateway Interface.
ASGI is designed to support asynchronous applications and modern communication patterns.
It is useful for Django applications that need capabilities such as:
- Asynchronous Views
- WebSockets through compatible tools
- Long-lived connections
- Other asynchronous workloads
Django projects include ASGI configuration so the application can be served by an ASGI-compatible server.
Understanding the Django App Structure
When you create a Django app, you’ll commonly see:
blog/
├── __init__.py
├── admin.py
├── apps.py
├── models.py
├── tests.py
├── views.py
└── migrations/
Each file has a specific purpose.
| File/Folder | Purpose |
|---|---|
admin.py | Django admin configuration |
apps.py | App configuration |
models.py | Database models |
views.py | Request handling |
tests.py | Automated tests |
migrations/ | Database schema changes |
__init__.py | Python package initialization |
You can add additional files as the application grows.
Where Should Forms Go?
For applications using Django’s built-in form system, forms are commonly placed in:
forms.py
For example:
blog/
├── models.py
├── forms.py
├── views.py
└── urls.py
Forms can handle:
- User input
- Validation
- Model forms
- File uploads
- Form processing
Large applications may organize forms into a dedicated package.
Where Should Serializers Go?
If you’re using Django REST Framework, serializers are commonly placed in:
serializers.py
For example:
api/
├── models.py
├── serializers.py
├── views.py
└── urls.py
Serializers help convert complex Django objects into data formats such as JSON and validate incoming API data.
Where Should Business Logic Go?
As your Django application grows, placing all business logic inside views.py can make the code difficult to maintain.
For larger projects, you might introduce a dedicated service layer.
For example:
services/
├── order_service.py
├── payment_service.py
└── notification_service.py
This allows Views to focus primarily on request handling while business operations are organized separately.
There is no single mandatory Django structure for this.
The best approach depends on the size and complexity of the application.
A Scalable Django Project Structure
A larger Django application might eventually look like:
project/
│
├── manage.py
│
├── config/
│ ├── settings/
│ ├── urls.py
│ ├── asgi.py
│ └── wsgi.py
│
├── apps/
│ ├── accounts/
│ ├── products/
│ ├── orders/
│ └── payments/
│
├── templates/
├── static/
├── media/
├── requirements/
└── tests/
This is not required for every Django application.
However, separating configuration, applications, templates, static files, and tests can make larger projects easier to manage.
What Is the config Folder?
Many production Django projects rename the default project package to something such as:
config/
This folder contains project-level configuration such as:
- Settings
- Root URLs
- ASGI configuration
- WSGI configuration
For example:
config/
├── settings/
├── urls.py
├── asgi.py
└── wsgi.py
The name config is simply a convention.
Django doesn’t require the folder to have this exact name.
Splitting Django Settings
For larger applications, developers sometimes split settings.py into multiple files.
For example:
settings/
├── __init__.py
├── base.py
├── development.py
└── production.py
This can make it easier to manage different environments.
For example:
Development
Used on a developer’s local machine.
Production
Used on the live server.
This approach can help keep environment-specific settings organized.
Where Should Environment Variables Go?
Sensitive configuration should generally not be hard-coded directly into source code.
Examples include:
- Database passwords
- Secret keys
- API keys
- Cloud storage credentials
- Email credentials
These values are commonly provided through environment variables or a secure configuration system.
This is especially important when deploying Django applications to production.
Django Project Structure for APIs
If you’re building a Django REST API, your structure may look different from a traditional server-rendered Django application.
For example:
project/
├── manage.py
├── config/
│ ├── settings.py
│ └── urls.py
│
└── users/
├── models.py
├── serializers.py
├── views.py
├── urls.py
└── tests.py
Instead of primarily returning HTML templates, API Views commonly return JSON responses.
Django Templates and APIs
A traditional Django website may use:
Models → Views → Templates → HTML
A Django REST API commonly uses:
Models → Serializers → API Views → JSON
This difference can influence how you organize your applications.
For modern projects, Django is frequently used purely as a backend API while a separate frontend application handles the user interface.
Where Should Static and Media Files Be Stored?
A common project structure is:
project/
├── static/
│ ├── css/
│ ├── js/
│ └── images/
│
└── media/
├── profiles/
├── products/
└── documents/
Remember:
Static = Application assets
Media = User-uploaded files
Keeping this distinction clear is important when deploying Django applications.
Django Project Structure Best Practices
A good Django structure should make it easy to answer:
“Where does this code belong?”
Some useful practices include:
Keep Apps Focused
Each app should generally represent a meaningful area of functionality.
Avoid Huge views.py Files
If Views become very large, move reusable business logic into appropriate modules.
Keep Models Focused
Models should define data structure and model-related behavior rather than becoming a dumping ground for unrelated logic.
Separate Configuration
For larger projects, consider separating development and production settings.
Organize Templates
Use folders based on applications or features.
Organize Static Files
Keep CSS, JavaScript, images, and other static assets structured.
Use Environment Variables
Keep secrets and environment-specific configuration outside your source code.
Write Tests
Organize tests so developers can easily find and maintain them.
Common Django Project Structure Mistakes
Putting Everything in One App
Small applications may start with one app, but larger projects often benefit from separating major features.
Creating Too Many Apps
On the other hand, creating an app for every tiny feature can make the project unnecessarily complicated.
Apps should represent meaningful boundaries.
Putting All Logic in Views
Large Views can become difficult to test and maintain.
Consider moving complex business operations into services or other appropriate modules.
Mixing Static and Media Files
Keep application-provided static assets separate from user-uploaded media.
Hard-Coding Secrets
Never commit sensitive credentials directly into your source code.
Ignoring Project Growth
A structure that works for a small project may need to evolve as the application becomes larger.
How Django Files Work Together
A simple Django request can be understood like this:
User Request
↓
urls.py
↓
View
↓
Model / Database
↓
Template or Serializer
↓
Response
For a traditional Django website:
Browser
↓
URL
↓
View
↓
Model
↓
Template
↓
HTML Response
For a Django REST API:
Client
↓
API URL
↓
API View
↓
Model
↓
Serializer
↓
JSON Response
Understanding these relationships makes the Django project structure much easier to remember.
A Simple Mental Model for Django Beginners
You don’t need to memorize every file immediately.
Start with these core concepts:
manage.py
Manage the project
settings.py
Configure the project
urls.py
Route requests
views.py
Handle requests
models.py
Define database data
templates/
Display HTML
serializers.py
Convert and validate API data
migrations/
Track database changes
admin.py
Configure Django admin
Once you understand these responsibilities, most Django project structures become much easier to navigate.
Frequently Asked Questions
What is Django project structure?
Django project structure is the organization of files and directories that make up a Django project and its applications.
What is the difference between a Django project and an app?
A Django project is the overall application configuration, while a Django app is a component focused on a particular feature or functionality.
What is manage.py used for?
manage.py provides a command-line interface for performing common Django project tasks such as running the development server, migrations, creating apps, and running tests.
What is settings.py in Django?
settings.py contains the configuration for a Django project, including database settings, installed apps, middleware, templates, static files, and security-related settings.
What is urls.py used for?
urls.py defines URL patterns and connects URLs to the appropriate Views.
What is models.py used for?
models.py contains Django model definitions that represent application data and database structures.
What is views.py used for?
views.py contains request-handling logic and determines what response should be returned to the client.
Where should HTML templates be stored?
Templates can be stored in a project-level templates/ directory or inside individual Django apps, depending on the project’s organization.
Where should CSS and JavaScript files be stored?
CSS, JavaScript, and other application assets are generally managed as Django static files.
Where should uploaded images be stored?
User-uploaded images and other files are generally handled as media files using Django’s media storage configuration.
Can I change the default Django project structure?
Yes. Django provides conventions rather than forcing one exact directory structure. Larger applications often introduce additional folders and modules to improve organization.
Conclusion
Understanding the Django project structure is one of the most important steps for Django beginners.
The default structure provides a clear foundation:
manage.py manages the project.
settings.py contains configuration.
urls.py handles URL routing.
views.py handles requests and responses.
models.py defines database structures.
templates handle HTML presentation.
static contains application assets.
media contains user-uploaded files.
migrations track database schema changes.
As your application grows, you can introduce additional structures such as services, serializers, separate settings, dedicated test packages, and feature-focused Django apps.
The goal isn’t to follow one rigid folder structure. The goal is to create an organization that makes your code easy to find, understand, test, and maintain.
Once you understand the responsibility of each major Django file and folder, navigating existing Django projects becomes much easier—and building your own Django applications becomes more organized from the beginning.
