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.

Practice

1. What is the correct command to create a new Django project named mywebsite?

easy

A. django-admin startproject mywebsite

B. django startproject mywebsite

C. django-admin createproject mywebsite

D. django-admin newproject mywebsite

Solution

1. Step 1: Understand the Django project creation command

   The official command to create a new Django project is django-admin startproject projectname.

2. Step 2: Match the command with the project name

   Replacing projectname with mywebsite gives django-admin startproject mywebsite.

3. Final Answer:

   django-admin startproject mywebsite -> Option A

4. Quick Check:

   Correct command = django-admin startproject mywebsite [OK]

Hint: Use 'django-admin startproject' plus your project name [OK]

Common Mistakes:

• Using 'django startproject' instead of 'django-admin startproject'
• Using 'createproject' or 'newproject' which are invalid commands
• Forgetting to specify the project name

2. Which of the following commands has the correct syntax to create a Django project called blog?

easy

A. django-admin startproject blog

B. django-admin start project blog

C. django-admin startprojectblog

D. django-admin create project blog

Solution

1. Step 1: Check the command syntax

   The correct syntax is django-admin startproject projectname without spaces inside the command words.

2. Step 2: Identify the correct option

   django-admin startproject blog matches the correct syntax exactly: django-admin startproject blog.

3. Final Answer:

   django-admin startproject blog -> Option A

4. Quick Check:

   Correct syntax = django-admin startproject blog [OK]

Hint: No spaces inside 'startproject', write as one word [OK]

Common Mistakes:

• Adding spaces inside 'startproject' command
• Combining command and project name without space
• Using 'create' instead of 'startproject'

3. After running django-admin startproject testsite, which folder structure will be created?

medium

A. A folder named testsite with only one file settings.py

B. A folder named testsite containing only manage.py file

C. A folder named testsite containing manage.py and urls.py only

D. A folder named testsite containing manage.py and a subfolder testsite with settings files

Solution

1. Step 1: Recall Django project folder structure

   Running django-admin startproject testsite creates a folder testsite with manage.py and a subfolder testsite containing settings.py, urls.py, asgi.py, and wsgi.py.

2. Step 2: Match the correct folder structure

   A folder named testsite containing manage.py and a subfolder testsite with settings files correctly describes this structure with manage.py and a subfolder testsite holding settings files.

3. Final Answer:

   Folder with manage.py and subfolder testsite with settings files -> Option D

4. Quick Check:

   Default Django project structure = A folder named testsite containing manage.py and a subfolder testsite with settings files [OK]

Hint: Remember: project folder has manage.py plus inner folder with settings [OK]

Common Mistakes:

• Expecting all files in one folder without subfolder
• Thinking only manage.py is created
• Confusing project folder and app folder structure

4. You ran django-admin startproject mysite but got an error: django-admin: command not found. What is the likely cause?

medium

A. You need to run the command inside an existing Django project folder

B. You typed the project name incorrectly

C. Django is not installed or not in your system PATH

D. The command should be django startproject mysite

Solution

1. Step 1: Understand the error message

   The error django-admin: command not found means the system cannot find the django-admin command.

2. Step 2: Identify the cause

   This usually happens if Django is not installed or the Python scripts folder is not in your system PATH environment variable.

3. Final Answer:

   Django is not installed or not in your system PATH -> Option C

4. Quick Check:

   Command not found = Django missing or PATH issue [OK]

Hint: Check Django installation and PATH if 'command not found' error appears [OK]

Common Mistakes:

• Assuming project name typo causes command not found
• Trying to run command inside project folder before creating it
• Using wrong command syntax instead of fixing PATH

5. You want to create a Django project named shop inside a folder websites that already exists. Which is the correct way to do this?

hard

A. Run django-admin startproject websites/shop from any folder

B. Navigate to the websites folder in terminal, then run django-admin startproject shop

C. Create the shop folder manually inside websites then run django-admin startproject shop

D. Run django-admin startproject shop websites from the parent folder

Solution

1. Step 1: Understand how startproject creates folders

   The startproject command creates a new folder with the project name in the current directory.

2. Step 2: Choose the correct folder navigation

   To create shop inside websites, first go into websites folder, then run django-admin startproject shop.

3. Final Answer:

   Navigate to websites folder, then run django-admin startproject shop -> Option B

4. Quick Check:

   Run command inside target folder to create project there [OK]

Hint: Change directory to target folder before running startproject [OK]

Common Mistakes:

• Trying to specify nested folder in startproject command
• Creating folders manually before running startproject
• Passing folder name as second argument to startproject