Setting Up Your First Django Project

Welcome to Module 4! In the previous module, you built a solid foundation in core Python, mastering object-oriented programming, error handling, logging, and, most importantly, automated testing with pytest. These skills are the bedrock upon which professional backend systems are built. Now, we transition from writing standalone Python scripts to building powerful, full-featured web applications using the Django framework.

This first lesson is your entry point into the world of Django. We will start from the very beginning, demystifying what a web framework is and how Django structures a web application. You will learn to initialize a project, create your first application within it, and understand the core configuration file that orchestrates everything. By the end of this lesson, you will have created the complete, albeit empty, skeleton of a Django web application, ready for us to flesh out in the lessons to come.

1. What is a Web Framework?

Before we write any code, it's crucial to understand why we use a framework like Django. A web framework provides a standard way to build and deploy web applications. It handles the common, repetitive tasks—like routing URLs to code, interacting with databases, and managing user sessions—so you can focus on the unique logic of your application.

Django is known for its "batteries-included" philosophy. This means it comes with a vast array of built-in features, such as a powerful Object-Relational Mapper (ORM) for database operations, an automatic admin interface, and a robust authentication system. This philosophy is why companies like Instagram and Spotify have used it to scale.

The following video from Programming with Mosh provides an excellent high-level overview of Django's role in the web development ecosystem.

Django Tutorial for Beginners – Build Powerful Backends

This video introduces Django, explains the client-server model, and distinguishes between frontend and backend development.

Watch the introductory section to understand the "big picture" of web development with Django. Pay close attention to: What Django is: Understand the "batteries-included" philosophy. Client-Server Model: This section clarifies the roles of the client (browser) and the server (your Django backend) and the concept of an API, which will be central to this course.

2. Project and App Structure

Django has a specific and important distinction between a project and an app.

A Project is the entire web application. It houses all the configuration, settings, and a collection of apps that work together. Think of it as the container for your website.
An App is a self-contained module within a project that performs a specific function. For example, you might have a users app for authentication, a blog app for posts, and a store app for products. Good Django development is about building small, reusable apps.

The image below illustrates a typical, well-structured Django project. You can see the main project folder, a folder for apps, and other directories for templates and static files which we'll cover later.

A diagram showing the hierarchical structure of a Django project. It highlights the main project directory (containing `settings.py`), the `manage.py` script, and separate folders for multiple applications (`app_1`, `app_2`).

3. Creating Your First Django Project

Let's get our hands dirty. The process begins in the terminal, where we'll set up our environment and use Django's command-line tools to generate the project skeleton. The following guide from Real Python walks you through this process with precise commands.

Your First Steps With Django: Set Up a Django Project

This article provides a clear, step-by-step walkthrough for setting up a virtual environment, installing Django, and creating the initial project structure.

Please follow the instructions in the first three steps of the article: Read Step 1 to create a new project directory and a virtual environment within it. You are already familiar with this from Module 2. Follow Step 2 to install Django using pip and create a requirements.txt file. This is crucial for project reproducibility. Execute the commands in Step 3. This section introduces the django-admin startproject command. It's common practice to use the variation with a dot (.) at the end, like django-admin startproject myproject ., to create a flatter, more manageable directory structure.

After completing these steps, your project directory will contain a manage.py file and a sub-directory named after your project (e.g., setup/ in the article's example). This sub-directory is your project configuration folder.

4. The `settings.py` File: The Heart of Your Project

Inside your project configuration folder lies settings.py. This file is the central control panel for your entire Django application. It's a Python module where you define everything from database connections to installed apps and security keys.

The following guide provides a comprehensive tour of the most important variables in a default settings.py file.

Understanding Django's settings.py File: A Comprehensive Guide for Beginners - DEV Community

This article breaks down the default settings file into logical sections, explaining the purpose of each key configuration.

Read through the descriptions of these fundamental settings. You don't need to memorize them all, but you should understand their purpose: Base Directory: How Django locates your project on the file system. Secret Key: A critical security setting. Debug Mode: What it means to have DEBUG = True and why it must be False in production. Allowed Hosts: A security measure to protect your site. Installed Apps: The registry of all apps active in your project. We will edit this soon. Database Configuration: Where you tell Django how to connect to your database. We'll start with the default, SQLite.

5. Creating and Registering an App

Now that we have a project, let's create our first app. An app contains the specific functionality of a part of your site. We use the manage.py script for this.

The following video segment demonstrates this process clearly.

Django Tutorial for Beginners – Build Powerful Backends

This part of Mosh's tutorial shows how to create a new app and, crucially, how to register it with your project.

Watch this section carefully: Creating an App: See the python manage.py startapp command in action. App Structure: Get a walkthrough of the files generated inside the new app's directory (models.py, views.py, etc.). Registering the App: Observe the final, essential step of adding the new app's name to the INSTALLED_APPS list in settings.py.

Every time you create a new app, you must register it in settings.py. If you forget this step, Django won't know the app exists and none of its models, views, or URLs will work.

6. Running the Development Server

With our project and app structure in place, we can run Django's built-in development server. This is a lightweight web server you can use while developing. It is not suitable for production but is perfect for our current needs.

To start it, run the following command from the same directory as your manage.py file:

python manage.py runserver

This will start the server, typically on http://127.0.0.1:8000/. The video below shows what you should see.

Python Django Tutorial: Full-Featured Web App Part 1 - Getting Started

This short clip from Corey Schafer's tutorial shows how to run the development server and view the default success page in your browser.

Watch from running the server to see the command and the resulting webpage. This confirms your installation and setup are successful.

Seeing the "The install worked successfully!" page is your confirmation that the project skeleton is correctly configured.

Hands-On Task: Build a "TaskMaster" Project Skeleton

Now, let's put everything together to create the foundation for our first mini-project, a simple task manager.

Create Project Directory: On your machine, create a new folder called taskmaster_project.
Set Up Environment: Navigate into this folder in your terminal. Create and activate a Python virtual environment.
Install Django: Use pip to install Django.
Pin Dependencies: Create a requirements.txt file by running pip freeze > requirements.txt.
Initialize Project: Inside the taskmaster_project directory, run the command to create a new Django project named config. Use the . at the end of the command to ensure a flat structure.
```
django-admin startproject config .
```
Create App: Create a new app for managing our tasks.
```
python manage.py startapp tasks
```
Register App: Open the config/settings.py file. Find the INSTALLED_APPS list and add 'tasks' to it.
Verify Setup: Run the development server.
```
python manage.py runserver
```
Open your web browser and navigate to http://127.0.0.1:8000/. You should see the Django success page.

You have now successfully created the complete file structure for a new Django project. Keep this terminal window with the running server open; you can stop it anytime by pressing Ctrl+C.

Conclusion

In this lesson, you took the crucial first step from being a Python programmer to becoming a Django developer. You learned the fundamental distinction between a project and an app, used Django's command-line tools to scaffold a new application, and familiarized yourself with the all-important settings.py file.

Key Takeaways:

A Django Project is the container for your entire website's configuration and apps.
A Django App is a modular component that handles a specific piece of functionality.
The django-admin startproject command creates the project skeleton.
The python manage.py startapp command creates an app within the project.
All new apps must be registered in the INSTALLED_APPS list in settings.py.
The python manage.py runserver command starts a local development server for testing.

You now have a clean, working foundation. In the next lesson, we will bring our application to life by defining its data structure. You'll learn how to create your first Django Model, which represents a database table, and how to use migrations to apply those changes to the database.

Recommended resources