Educational

Running the Development Server

—

by

Saim Khalid
in

Introduction

Django is one of the most popular and powerful web frameworks in the Python ecosystem. Known for its speed, security, and scalability, Django enables developers to build complex web applications efficiently. Before you can deploy a Django application to production, it’s important to first learn how to run and test it locally using the Django development server.

In this comprehensive guide, we’ll explore in detail how to start, configure, and test your first Django development server on your local machine. We will go step by step—from installation and setup to troubleshooting common errors—so that by the end of this tutorial, you will be confident in running and testing Django projects locally.

Understanding the Django Development Server

The Django development server is a lightweight web server that comes built into Django. It allows developers to run their Django applications locally without needing to configure a full production web server like Apache or Nginx.

The main purpose of the Django development server is to make the development and testing process faster and simpler. It is not intended for production use because it’s not optimized for handling high traffic, security hardening, or complex deployment setups. However, for local development, it’s perfectly suited.

When you create a Django project, the manage.py script includes a built-in command to run the server. This command is typically:

python manage.py runserver

This command launches the Django development server, making your project accessible via a web browser on a specific port—by default, port 8000. Once running, Django automatically detects changes you make to your code and reloads the server, making the development experience fast and convenient.

Prerequisites Before Starting

Before starting your Django development server, ensure that your local environment is properly set up. Here’s what you need:

  1. Python Installed
    Django is a Python framework, so you must have Python installed on your system. You can verify this by running: python --version or python3 --version It’s recommended to use Python 3.8 or higher.
  2. Pip Installed
    Pip is the package installer for Python. It allows you to install Django and other dependencies easily. You can check if pip is installed using: pip --version
  3. Virtual Environment (Optional but Recommended)
    Virtual environments help you manage dependencies for different projects separately. To create a virtual environment, you can use: python -m venv env Then activate it:
    • On Windows: env\Scripts\activate
    • On macOS/Linux: source env/bin/activate
  4. Django Installed
    Once your virtual environment is active, install Django: pip install django To confirm installation: django-admin --version

With these prerequisites met, you’re ready to create your first Django project.

Creating Your First Django Project

To start a Django project, you’ll use the django-admin command-line utility. Let’s create a new project named myproject:

django-admin startproject myproject

This command creates a directory structure like this:

myproject/

manage.py
myproject/
    __init__.py
    settings.py
    urls.py
    asgi.py
    wsgi.py

Each of these files serves a purpose:

  • manage.py: A command-line utility for running server commands and managing the project.
  • settings.py: Contains configuration details such as installed apps, middleware, database settings, and more.
  • urls.py: Defines URL routes for your application.
  • wsgi.py and asgi.py: Used for deployment; they help connect Django with different web servers.

Once the project is created, navigate into your project folder:

cd myproject

Now you are ready to start your Django development server for the first time.

Running the Django Development Server

To start the Django server, use the following command:

python manage.py runserver

After running this command, you should see output similar to:

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
October 13, 2025 - 12:00:00
Django version 5.x, using settings 'myproject.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

This means your Django development server is successfully running.

Now, open your web browser and go to the URL displayed in the terminal—usually:

http://127.0.0.1:8000/

You should see Django’s default welcome page, which confirms that everything is working correctly.

Understanding the Default Server Address and Port

By default, when you run python manage.py runserver, Django binds to the local IP address 127.0.0.1 (localhost) and uses port 8000. You can change this if needed.

For example, to use a different port, you can specify it as an argument:

python manage.py runserver 8080

This will start the server on port 8080 instead of 8000.

To make your server accessible to other devices on your local network, use the following syntax:

python manage.py runserver 0.0.0.0:8000

This binds the server to all available IP addresses on your computer. However, be cautious—this exposes your development server to other devices, which can pose security risks if your network is not secure.

Automatic Code Reloading

One of Django’s most useful features for developers is automatic code reloading. Whenever you modify your Python files, Django detects these changes and automatically restarts the development server.

This means you can instantly test your code changes without manually restarting the server every time. However, note that changes in certain files—like those related to database migrations—might require a manual restart.

Creating a Simple Django App

To test your Django server further, let’s create a simple app within your project. In Django, a “project” is a collection of settings and configurations, while an “app” is a module that performs specific functions within the project.

Run the following command inside your project directory:

python manage.py startapp hello

This creates a directory named hello with the following structure:

hello/

__init__.py
admin.py
apps.py
models.py
tests.py
views.py

Next, open hello/views.py and add a simple view:

from django.http import HttpResponse

def home(request):

return HttpResponse("Hello, Django Server is Running Successfully!")

Now, connect this view to a URL. In the main project’s myproject/urls.py, add the following:

from django.contrib import admin
from django.urls import path
from hello import views

urlpatterns = [

path('admin/', admin.site.urls),
path('', views.home),
]

Save your files, then run the server again:

python manage.py runserver

When you visit http://127.0.0.1:8000/, you should now see the message:

Hello, Django Server is Running Successfully!

Congratulations—you’ve successfully built and tested your first Django server and app locally.

Working with Database Migrations

Django includes a powerful ORM (Object-Relational Mapper) that manages database operations. Before your project can interact with the database, you must run migrations to create the necessary tables.

Run the following commands:

python manage.py makemigrations
python manage.py migrate

These commands set up the default database (SQLite by default). Django automatically creates tables for built-in apps such as authentication and sessions.

If you later define models in your app, you’ll use the same commands to create and apply migrations.

Creating a Superuser

To access Django’s admin interface, you need a superuser account. Create one using:

python manage.py createsuperuser

You’ll be prompted for a username, email, and password. Once done, start your server again and go to:

http://127.0.0.1:8000/admin/

Log in using your superuser credentials. You’ll now see Django’s admin dashboard—one of Django’s most powerful built-in tools for managing data.

Testing Your Django Server

Once your server is up and running, you can perform various tests to ensure everything works properly.

1. Checking Server Logs

When running the development server, Django prints detailed logs in the terminal. These logs include server startup messages, HTTP requests, warnings, and errors. Monitoring these logs helps identify issues quickly.

2. Using Django’s Debug Mode

By default, DEBUG = True in settings.py. This enables detailed error pages and stack traces, which are helpful during development. However, remember to set DEBUG = False in production for security reasons.

3. Creating Unit Tests

Django includes a built-in testing framework based on Python’s unittest. You can create test cases in tests.py files and run them using:

python manage.py test

This helps ensure that your application’s views, models, and logic behave as expected.

Common Issues and How to Fix Them

While running your Django server, you might encounter some common errors. Here are a few and their solutions:

1. Port Already in Use

Error Message:

Error: That port is already in use.

Solution:
Specify a different port when starting the server:

python manage.py runserver 8081

2. Database Locked or Migration Errors

If you encounter database issues, you can try deleting the existing SQLite file (db.sqlite3) and reapplying migrations:

rm db.sqlite3
python manage.py migrate

3. Import Errors

Ensure that your app is added to the INSTALLED_APPS list in settings.py. For example:

INSTALLED_APPS = [

'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'hello',  # Your app name
]

4. Static Files Not Loading

During development, ensure you’ve added:

python manage.py collectstatic

Or configure static files properly in settings.py with:

STATIC_URL = '/static/'

Using Environment Variables for Configuration

It’s a good practice not to hardcode sensitive information (like secret keys or database credentials) in your settings file. You can use environment variables instead.

For example, in settings.py:

import os

SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'fallback-secret-key')

You can then set environment variables in your terminal before running the server:

export DJANGO_SECRET_KEY='mysecret'

This makes your configuration more secure and flexible.

Advanced Server Configuration

Django’s development server can be customized using command-line arguments and configuration options.

1. Custom IP and Port

python manage.py runserver 192.168.1.10:9000

2. Disable Auto-Reload

python manage.py runserver --noreload

3. Verbose Output

To get detailed server logs:

python manage.py runserver --verbosity 3

These options allow more control during local testing.

Deploying Beyond the Development Server

Although Django’s development server is excellent for local testing, it’s not recommended for production. When your app is ready to go live, you’ll need a more robust setup using:

  • Gunicorn or uWSGI for serving Python applications.
  • Nginx or Apache as a reverse proxy.
  • Databases like PostgreSQL or MySQL.
  • Static files management using whitenoise or a CDN.

The skills you gain by running Django locally will help you transition easily into deploying your application in a production environment.

Best Practices for Local Development

Here are some best practices to follow while developing locally with Django:

  1. Use a virtual environment to isolate project dependencies.
  2. Enable debug mode only during development.
  3. Regularly check logs for warnings or errors.
  4. Use version control (Git) to manage your codebase.
  5. Document your configuration settings to ease collaboration.
  6. Test thoroughly before deployment.

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *