Author: @nextgenkhushal
Hello, and welcome to your first foray into the world of Django! If you're looking to build powerful web applications, you've come to the right place. This guide will take you from an empty folder to a running Django application, step by step, with clear explanations at every turn.
Django is a high-level Python web framework that encourages rapid development and clean, pragmatic design. It's famous for being "ridiculously fast," allowing you to go from concept to completion with incredible speed. Django is also a mature and secure framework trusted by major companies like Instagram and Paytm to power their services.
The goal of this tutorial is simple: we will guide you step-by-step from an empty folder to a running Django application. We'll cover setting up your workspace, installing Django, creating your first project, and launching the development server. By the end, you'll understand not just how to get Django running, but why each step matters and how all the pieces fit together.
Before we dive into the technical setup, let's understand what makes Django special. There are many web frameworks out there, so why choose Django? Here are four compelling reasons that have made Django the choice of professional developers worldwide.
Django is designed for rapid development, taking you from idea to launch in record time. The framework comes with so many built-in features that you spend less time reinventing the wheel and more time building the unique parts of your application. What might take weeks in other frameworks can often be accomplished in days with Django.
Django is built to handle massive traffic on minimal hardware. It's trusted by giants like Instagram and Paytm, which means it's been battle-tested at scales most applications will never reach. When your application grows from hundreds to millions of users, Django won't be the bottleneck.
Django comes with a powerful toolkit right out of the box. This includes an admin panel that lets you manage your application's data without writing a single line of administrative code, a robust authentication system that handles users and permissions securely, and much more. These features alone can save you months of development time.
Security vulnerabilities can destroy an application's reputation overnight. Django helps developers avoid common security mistakes by providing built-in protection against threats like SQL injection, cross-site scripting, and clickjacking. The framework follows security best practices automatically, so you're protected even if you're still learning about web security.
Django is a mature, full-stack framework with a distinct approach to web development. Before you start comparing it to JavaScript frameworks like Next.js or NestJS, it's important to understand that they solve different problems in different ways. This isn't about one being better than the other; it's about understanding what you're working with.
Think of Django's philosophy as being closer to frameworks like Laravel or Ruby on Rails. These are frameworks where convention and a comprehensive toolkit guide your development process. JavaScript frameworks often give you more flexibility to choose your own tools and architecture, but Django provides a well-trodden path with proven patterns.
In the JavaScript ecosystem, you might spend time deciding which router to use, which state management library to adopt, and how to structure your backend API. Django makes many of these decisions for you, providing a cohesive system where everything works together smoothly. This "opinionated" approach means you can focus on building your application's unique features instead of assembling and configuring dozens of separate tools.
This mindset shift is important. Django isn't trying to be a JavaScript framework, and that's actually its strength. It brings decades of web development wisdom into a single, well-integrated package that works beautifully for building robust, scalable web applications.
Professional Python development is always done in isolated environments. Before we install anything, let's understand why this matters and how it works. This concept might seem like extra work at first, but it's actually one of the most important professional practices you'll learn.
Imagine you're working on several different projects. One project needs Django version 4.2, another needs Django 5.0, and a third project uses an entirely different web framework. If you installed all of these directly on your main computer, you'd quickly run into conflicts. Version 4.2 and 5.0 can't both be "the" Django installation on your system.
A virtual environment solves this elegantly by creating a self-contained sandbox for each project. All the packages and dependencies you install for your Django project will live inside this sandbox, completely separate from your main system and from other projects. This isolation brings two critical benefits.
First, it provides dependency isolation. Your project's specific package versions won't interfere with your main system or with other projects. Each project gets exactly what it needs, nothing more, nothing less.
Second, it ensures reproducibility. Any developer can recreate the exact same environment for your project. This is crucial when you're working in teams or when you need to deploy your application to a server. You can say with certainty, "This is exactly what my project needs to run," and anyone can replicate that environment perfectly.
This professional standard keeps everything clean and conflict-free, and once you're used to it, you'll never want to work without virtual environments again.
While pip is the standard Python package installer that you'll find in most tutorials, we're going to use a more modern tool called UV. UV is an extremely fast package manager written in Rust, and it's quickly becoming the preferred choice for professional Python development.
Think of UV like npm versus bun in the JavaScript world. Both handle the same tasks, but UV does everything at a significantly higher speed. Installation that might take minutes with pip happens in seconds with UV. This speed difference might not matter much when you're installing a single package, but as your projects grow and you're installing dozens of dependencies, that time adds up quickly.
The best part is that UV handles all the same tasks as pip, so you're not learning something completely different. The commands are intuitive, and the tool is designed to be a drop-in replacement for pip with better performance.
Before we can use UV, we need to install it. The installation command depends on your operating system.
If you're on macOS, you can use Homebrew:
brew install uvFor other operating systems, or if you prefer using pip to install UV itself (yes, you can use pip to install a pip replacement!), run:
pip install uvOnce installed, UV will be available system-wide, and you'll be able to use it to create virtual environments and install packages at lightning speed.
Now that we understand why virtual environments matter and have UV installed, let's create our project workspace and set up our isolated environment. We'll take this step by step, explaining what each command does and why it matters.
First, we need a dedicated home for our new project. Open your terminal and run these commands:
mkdir chai_aur_django && cd chai_aur_djangoThis single line actually does two things. The mkdir command creates a new folder called chai_aur_django, and the && operator chains this with a second command, cd chai_aur_django, which immediately moves you into that new folder. You're now inside your project's home directory.
If you're using a code editor like VS Code, this is a good time to open this folder in your editor. Having your terminal integrated into your editor makes the development process much smoother.
With your terminal positioned in the chai_aur_django folder, run this command:
uv venvThis creates a hidden .venv folder in your current directory. The leading dot makes this folder hidden in most file explorers, which is a common convention for environment folders. Inside this .venv folder lives your project's isolated Python installation and a space for all the packages you'll install.
Notice how much faster this is compared to traditional python -m venv commands. UV's speed advantage becomes immediately apparent even in this first step.
Creating the environment isn't enough; you need to "turn it on" or activate it. The command to do this differs slightly based on your operating system.
If you're on macOS or Linux, run:
source .venv/bin/activateIf you're on Windows, use:
.venv\Scripts\activateOnce activated, you'll see your terminal prompt change. It will now display (.venv) at the beginning of the line, typically in a different color or with special formatting. This is your visual confirmation that you are successfully working inside your project's virtual sandbox.
From this point forward, any Python packages you install or commands you run will use this isolated environment instead of your system's main Python installation. This protection is automatic and transparent—you don't need to do anything special to maintain it except keep the environment activated while you work.
When you're finished working on your project and close your terminal, the environment automatically deactivates. The next time you come back to work on this project, you'll simply need to run the activation command again before you start. This might feel like an extra step at first, but it quickly becomes second nature.
With your virtual environment active (you should see that (.venv) indicator in your terminal), installing Django becomes incredibly straightforward. UV makes this process remarkably fast.
Run this single command:
uv pip install DjangoNotice how fast UV resolves and installs the packages compared to traditional pip. This speed difference becomes even more noticeable as you install more complex packages with many dependencies. What you're witnessing is the power of a tool written in Rust, designed from the ground up for performance.
An important note here: Inside an active virtual environment, you can simply use pip and the environment ensures it points to the correct Python and package versions. However, we're using uv pip because UV's implementation is significantly faster. The syntax is nearly identical to regular pip, so you're not learning an entirely new tool.
The installation completes in moments, and you now have the entire Django framework installed inside your .venv sandbox. Django didn't touch your system Python installation, didn't interfere with any other projects, and is ready to use exclusively for this project.
Now that Django is installed, you have access to a powerful new command-line tool called django-admin. This utility performs administrative tasks, and the very first one we'll learn is startproject, which creates the skeleton of a new Django project.
Here's where we'll use a professional technique that keeps your project structure clean. Run this command:
django-admin startproject chai_aur_django .Notice that dot at the end? That period is crucial, and many tutorials skip it, leading to an unnecessarily nested folder structure. Let's understand what this command does and why the dot matters.
When you run django-admin startproject followed by a project name, Django creates a new directory with that name to hold your project files. If you don't include the dot, Django creates this structure:
chai_aur_django/ (Your main folder)
├── .venv/
└── chai_aur_django/ (Django creates this outer folder)
├── manage.py
└── chai_aur_django/ (The inner configuration folder)
├── __init__.py
├── settings.py
├── urls.py
└── wsgi.py
This creates an extra layer of nesting that serves no real purpose and makes your paths longer and more confusing. By adding the dot at the end of the command, you're telling Django to create the project in the current directory, avoiding this extra nesting. Your structure becomes much cleaner:
chai_aur_django/ (Your main folder)
├── .venv/ (The isolated virtual environment)
├── chai_aur_django/ (The Python package for your project)
│ ├── __init__.py
│ ├── settings.py
│ ├── urls.py
│ └── wsgi.py
└── manage.py (Your primary command-line utility)
This is a common and clean practice among experienced Django developers. The outer folder represents your entire project workspace, and the inner chai_aur_django folder is specifically your project's Python package containing all the configuration files.
After running startproject, Django has created several files and folders. Let's take a guided tour of what each piece does and why it exists. As a beginner, you don't need to understand every detail of every file, but knowing the purpose of the key components will help you navigate your project confidently.
This is the chai_aur_django folder at the top level. It's your project's home base, containing everything related to this application. You'll spend most of your time here, and this is where you'll run most of your Django commands.
This hidden folder contains your isolated Python environment with Django and any other packages you install. You generally won't look inside this folder or modify anything in it directly. Its presence in your project root is normal and expected.
This folder shares the name of your project and serves as the actual Python package for your project's configuration. Inside it, you'll find several important files.
The __init__.py file is empty but crucial. Its presence tells Python that this directory should be treated as a Python package, allowing you to import from it elsewhere in your project.
Django created several Python files that control different aspects of your project.
settings.py is the most important file in your project. This is Django's control panel, holding all your project's configuration. It specifies which apps are installed, how to connect to your database, security settings, paths to templates and static files, and much more. As you build your application, you'll frequently return to this file to adjust settings or add new configurations.
urls.py serves as your project's table of contents. It maps URL paths like /about or /contact to the correct parts of your application. When someone visits a page on your site, Django consults this file to determine which code should handle that request. Think of it as a receptionist that directs visitors to the right office.
asgi.py and wsgi.py are gateway interfaces used when you deploy your application to a production server. WSGI (Web Server Gateway Interface) is the standard for Python web applications, while ASGI (Asynchronous Server Gateway Interface) handles more modern async capabilities. You won't touch these files during development, but they're essential when your application goes live.
The manage.py file sits at your project root and serves as your primary tool for interacting with your Django project. You'll use this file constantly. It handles running the development server, creating database migrations, opening the Django shell, and dozens of other development tasks.
Think of manage.py as your project's command center. Almost every action you take during development will start with python manage.py followed by a specific command.
The moment of truth has arrived. With all the pieces in place, it's time to see your Django application come to life in a web browser. This is where all your setup work pays off.
Make sure your virtual environment is still active (you should see that (.venv) indicator), and make sure you're in the same directory as the manage.py file. Then run:
python manage.py runserverYour terminal will fill with output as Django performs system checks and starts the development server. You'll see messages indicating that Django version 5.0 is running, using your project's settings. Near the bottom of the output, you'll see the crucial line:
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
By default, Django's built-in development server starts running on port 8000. The address 127.0.0.1 is a special address that means "this computer"—it's how your computer refers to itself. Together, http://127.0.0.1:8000/ means "run a web server on this computer on port 8000."
Open your web browser and navigate to http://127.0.0.1:8000/ (you can also use http://localhost:8000/, which means the same thing). You should be greeted by a page that says "The install worked successfully! Congratulations!"
This welcome page is visible because your project's settings.py file has debugging mode turned on with DEBUG = True. This setting is perfect for development because it shows you detailed error messages and helpful information. In production, you'll set this to False for security reasons, but during development, it's incredibly useful.
Congratulations! You have successfully created and launched your very first Django application. That colorful success page represents the foundation of what could become a powerful web application. Everything is working correctly, and you're ready to start building.
It's quite common to encounter an error message that says something like "Port is already in use." This happens when another application on your computer is already using port 8000. Many development tools use this port by default, so conflicts are frequent.
Getting a "Port is already in use" error is common, especially if you run other development servers that use port 8000 by default. The fix is simple: just specify a different port when you start your server. Django allows you to choose any available port number.
Try running:
python manage.py runserver 8001You can use port 8001, 8080, or any other available port number. Then, visit http://127.0.0.1:8001/ in your browser instead of the default 8000. The port number you choose doesn't matter for development; it's just a channel for the server to communicate through.
Now that your server is running, let's understand the purpose of the key files Django created. When you're new to a framework, seeing all these files can feel overwhelming. Let's break down what each one does in practical terms.
This is your primary tool for interacting with your project. You'll use it to run the development server (which you just did), create database migrations when you define data models, open the Django shell for testing code, create new apps within your project, and much more. Almost every action during development starts with python manage.py followed by a specific command. Think of this as your project's Swiss Army knife.
This file is the central configuration for your entire project. It controls which databases your project connects to, which apps are installed and active, security keys for production, paths to templates and static files, and numerous other settings. As you build your application, you'll frequently return to this file to adjust configurations or enable new features. Understanding this file is crucial to mastering Django.
This file contains a list of URL patterns. It's the table of contents that maps incoming browser requests to the correct part of your application. When someone visits a page on your site, Django looks at the URL they requested, checks this file to find a matching pattern, and then routes the request to the appropriate code to handle it. As your application grows, you'll add more URL patterns here to handle different pages and features.
When you ran the development server for the first time, Django automatically created this lightweight database file. SQLite is perfect for development and small projects because it requires no setup—Django created it automatically and it lives right in your project folder as a single file. Django's powerful ORM (Object-Relational Mapping) system means you can easily switch to PostgreSQL or MySQL later by changing just one line in your settings. For learning and development, SQLite is ideal.
Understanding how Django processes a web request is fundamental to building applications with confidence. Let's trace the journey of a single request from start to finish, seeing how all these pieces work together.
The lifecycle begins when a user types a URL into their browser and hits enter. Their browser sends a GET request to your Django server asking for that page. This request arrives at Django, which immediately checks the URL against the patterns defined in your urls.py file. Django is looking for a pattern that matches the requested URL.
When Django finds a matching pattern in urls.py, it knows which view function should handle this request. The view is where your business logic lives. This is a function you'll write in a file called views.py (you'll create this file when you build your first app).
The view function executes your code. It might fetch data from the database using models defined in models.py, perform calculations, or make decisions based on the request. Eventually, the view needs to send something back to the user's browser. This response can be simple text, rendered HTML from a template, JSON data for an API, or anything else a browser can understand.
Django then returns this response to the user's browser, which displays the result. The entire cycle completes in milliseconds, and Django is ready for the next request.
Right now, you don't have any custom views or URL patterns—that's why you see Django's default welcome page. But as you build your application, you'll create view functions and URL patterns to handle different pages, and this request-response cycle will power everything your application does.
You've successfully set up your environment, created a Django project, and launched the development server. This foundation is where every professional Django application begins. The structure is in place, and you're ready to start building.
Your next steps in this journey will involve creating your first app to organize your code, defining data structures in models.py to work with databases, writing business logic in views.py to handle requests and responses, and building user interfaces with templates to display your content beautifully.
Each of these topics builds on what you've learned today. Django's architecture separates concerns clearly—models handle data, views handle logic, templates handle presentation, and URLs handle routing. This separation makes it easy to understand where different pieces of your code should live.
The development server you just launched isn't just a one-time achievement. It's a tool you'll use every single day as you build. You'll make changes to your code, refresh your browser, and immediately see the results. This rapid feedback loop is what makes Django development so enjoyable and productive.
Let's take a moment to appreciate what you've accomplished. In this tutorial, you have set up a professional virtual environment using modern tools, installed the powerful Django framework, created a brand-new Django project with a clean structure, successfully ran the development server, and seen your first Django success page in the browser.
More importantly, you understand why each of these steps matters. You know that virtual environments protect your projects from conflicts, that UV gives you speed advantages in package management, that the dot in the startproject command keeps your structure clean, and that manage.py will be your constant companion throughout development.
This foundation is solid and professional. From here, your journey continues into the exciting world of building web applications. You'll learn how to create dynamic pages, work with databases, handle user authentication, build APIs, and deploy your applications to the web where others can use them.
The best part? Every Django application, no matter how complex or successful, started exactly where you are now—with a fresh project, a development server, and that satisfying "Congratulations!" page.
You're well on your way. Keep building, stay curious, and remember that every expert was once a beginner who decided to keep going.
Happy coding Guys!