Creating a Django project - Mechanics & Internals

Overview - Creating a Django project

What is it?

Creating a Django project means setting up the basic structure and files needed to build a web application using Django. It prepares folders and configuration files that help organize your code, manage settings, and run your website. This setup is the starting point before adding features like pages, databases, or user login.

Why it matters

Without creating a Django project first, you have no organized way to build or run your web app. It solves the problem of managing many files and settings by giving you a clear, standard structure. Without it, building a web app would be chaotic and error-prone, making it hard to develop, test, or share your work.

Where it fits

Before creating a Django project, you should know basic Python and how to install software. After this, you learn how to add apps inside the project, connect databases, and build web pages. Creating the project is the foundation step in the Django learning path.

Mental Model

Core Idea

Creating a Django project sets up a ready-made folder and file system that organizes your web app’s code and settings so you can build on it easily.

Think of it like...

It's like laying the foundation and blueprint for a house before you start building walls and rooms.

Django Project Structure
┌─────────────────────────────┐
│ myproject/                 │
│ ├── manage.py              │  # Command-line tool to run tasks
│ ├── myproject/             │  # Main project folder
│ │   ├── __init__.py        │  # Marks this as a Python package
│ │   ├── settings.py        │  # Configuration settings
│ │   ├── urls.py            │  # URL routing for the project
│ │   └── wsgi.py            │  # Server interface
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

Install Django and Python

Concept: Before creating a project, you must have Python and Django installed on your computer.

1. Install Python from python.org if not installed. 2. Open a terminal or command prompt. 3. Run: python -m pip install django This installs Django, the tool to create and manage projects.

Result

Django is installed and ready to use on your system.

Knowing how to install Django ensures you have the right tools to start any Django project.

2

Foundation

Run django-admin startproject

Concept: Use the django-admin command to create a new project folder with all necessary files.

In your terminal, run: django-admin startproject myproject This creates a folder named 'myproject' with the basic project files inside.

Result

A new folder 'myproject' appears with manage.py and a subfolder also named 'myproject' containing settings.py, urls.py, and other files.

This command automates creating the complex folder structure so you don’t have to set it up manually.

3

Intermediate

Understand project folder structure

🤔Before reading on: do you think manage.py is inside the inner or outer project folder? Commit to your answer.

Concept: Learn what each file and folder inside the project does and why they are organized this way.

The outer folder (myproject/) contains manage.py, a command tool to run your app. The inner folder (myproject/myproject/) contains: - settings.py: configuration like database and apps - urls.py: routes URLs to code - wsgi.py: server interface - __init__.py: marks it as a Python package

Result

You can confidently navigate the project files and know where to add settings or routes.

Understanding the folder roles helps you avoid confusion and errors when building your app.

4

Intermediate

Run the development server

🤔Before reading on: do you think the server runs automatically after project creation or needs a command? Commit to your answer.

Concept: Learn how to start the built-in server to see your project running in a browser.

1. Open terminal inside the outer project folder. 2. Run: python manage.py runserver 3. Open a browser and go to http://127.0.0.1:8000/ You will see the default Django welcome page.

Result

Your Django project is running locally and accessible via a web browser.

Knowing how to run the server lets you test your project instantly and see changes live.

5

Advanced

Customize settings.py basics

🤔Before reading on: do you think settings.py is only for database info or also controls other behaviors? Commit to your answer.

Concept: Learn how to adjust basic settings like allowed hosts and timezone to prepare your project for development.

Open settings.py and find: - ALLOWED_HOSTS: list of domain names your app can serve - TIME_ZONE: set your local timezone - INSTALLED_APPS: list of apps included Changing these helps your project work correctly in different environments.

Result

Your project is configured to accept requests from your machine and use correct time settings.

Understanding settings.py basics is key to adapting your project for real-world use and deployment.

6

Expert

Project creation internals and customization

🤔Before reading on: do you think django-admin startproject copies files or generates them dynamically? Commit to your answer.

Concept: Explore how django-admin creates the project files and how you can customize the template it uses.

django-admin uses a template directory inside Django’s installation to copy starter files. You can create your own project template to include custom settings or files. This is useful for teams to standardize project setups. You can also use options like --template to specify a custom template.

Result

You can create projects tailored to your needs or company standards automatically.

Knowing the creation process lets you automate and customize project setups, saving time and ensuring consistency.

Under the Hood

When you run django-admin startproject, Django copies a set of template files from its internal directory to your new project folder. These files include Python scripts and configuration files that define the project’s structure and behavior. The manage.py script acts as a command-line utility to interact with the project, while settings.py holds all configuration variables. The inner folder is a Python package that Django uses to organize code and settings logically. Running the development server launches a lightweight web server that reads these files to serve your app locally.

Why designed this way?

Django was designed to be easy to start but powerful enough for complex apps. The project structure separates configuration (settings.py) from commands (manage.py) and routing (urls.py) to keep concerns clear. Copying templates ensures consistency and reduces errors. This design balances simplicity for beginners with flexibility for experts. Alternatives like single-file apps were rejected because they don’t scale well for larger projects.

Project Creation Flow
┌───────────────┐
│ django-admin  │
│ startproject  │
└──────┬────────┘
       │ copies template files
       ▼
┌─────────────────────┐
│ New Project Folder   │
│ ├ manage.py         │
│ └ Inner Package     │
│   ├ settings.py     │
│   ├ urls.py         │
│   └ wsgi.py         │
└─────────────────────┘
       │
       ▼
┌─────────────────────┐
│ Runserver Command    │
│ reads settings.py    │
│ starts local server  │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does creating a Django project automatically create a database? Commit yes or no.

Common Belief: Creating a Django project sets up the database automatically and it’s ready to use.

Reality: The project creation only sets up configuration files; the database is created later when you run migrations.

Why it matters: Assuming the database exists can cause errors when trying to access data before migrations run.

Quick: Is manage.py the main project folder? Commit yes or no.

Common Belief: manage.py is the main project folder where all code lives.

Reality: manage.py is a script file in the outer folder used to run commands; the main project code is inside the inner folder.

Why it matters: Confusing manage.py as a folder leads to misplaced files and broken imports.

Quick: Does running startproject create apps automatically? Commit yes or no.

Common Belief: Creating a Django project also creates default apps for you to use.

Reality: The project only sets up the base structure; apps must be created separately with startapp.

Why it matters: Expecting apps to exist causes confusion when trying to add features or routes.

Quick: Does the development server run in production? Commit yes or no.

Common Belief: The development server started by runserver is suitable for production use.

Reality: The development server is only for local testing; production requires a real web server like Gunicorn or uWSGI.

Why it matters: Using the development server in production risks security and performance problems.

Expert Zone

1

The inner project folder is a Python package, which allows Django to import settings and modules cleanly; forgetting __init__.py breaks this.

2

Custom project templates can include pre-configured apps, middleware, or settings, speeding up team onboarding and enforcing standards.

3

manage.py sets the DJANGO_SETTINGS_MODULE environment variable automatically, which is why running commands from outside the project folder can fail.

When NOT to use

Creating a Django project is not suitable if you want a lightweight microservice or API-only backend; frameworks like Flask or FastAPI are better for minimal setups.

Production Patterns

In production, projects often use multiple settings files (development, staging, production) by extending the base settings.py created at project start. Teams also customize the startproject template to include logging, security settings, and CI/CD configs from the beginning.

Connections

Software Project Initialization

Creating a Django project is a specific example of initializing a software project with a standard structure.

Understanding Django project creation helps grasp the general idea of setting up any software project with organized files and configuration.

Operating System File Systems

The project creation process involves copying and organizing files and folders on your computer’s file system.

Knowing how file systems work helps understand why project structure matters and how commands like django-admin manipulate files.

Architecture Blueprinting

Creating a Django project is like blueprinting a building’s architecture before construction.

This connection shows how planning and structure are essential in both software and physical construction for successful outcomes.

Common Pitfalls

#1 Running django-admin startproject inside an existing folder causing nested folders.

Wrong approach:

mkdir myproject
cd myproject
django-admin startproject myproject

Correct approach:

django-admin startproject myproject
cd myproject

Root cause:

Starting the project inside a folder with the same name creates an extra nested folder, confusing the structure.

#2 Trying to run the server from outside the outer project folder.

Wrong approach:

cd ..
python manage.py runserver

Correct approach:

cd myproject
python manage.py runserver

Root cause:

manage.py must be run from its folder because it sets environment variables relative to its location.

#3 Editing settings.py without restarting the server and expecting changes to apply immediately.

Wrong approach:

Change ALLOWED_HOSTS in settings.py and keep the server running without restart.

Correct approach:

Change ALLOWED_HOSTS in settings.py and restart the server with Ctrl+C then python manage.py runserver.

Root cause:

The development server loads settings at start; changes require a restart to take effect.

Key Takeaways

Creating a Django project sets up a clear folder and file structure that organizes your web app’s code and settings.

The django-admin startproject command automates this setup, saving time and avoiding errors.

Understanding the roles of manage.py, settings.py, and urls.py is essential to navigate and build your app.

Running the development server lets you test your project locally before deploying it.

Knowing common pitfalls and how the project creation works internally helps you avoid confusion and customize your setup.