Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 77 ยท Getting Started

Installing Django and Your First Project

Install Django in a virtual environment, run startproject and startapp, learn what every generated file does, and start the development server.

In this lesson you will do what every Django developer does on day one: create an isolated Python environment, install Django, generate a project and an app, and run the development server. Then you will tour the files Django created so none of them feels mysterious.

Because a browser tab cannot start a web server or install packages into your system, the terminal steps are shown as read-only commands that you run on your own computer. The live examples run the very same Django code in your browser, including the real startproject and startapp commands writing into a temporary folder, so you can see exactly what you will get.

Prerequisites

You need a recent Python 3 (current Django releases require Python 3.10 or newer, and the newest ones need 3.12 or newer; check the release notes for your version) and a terminal. If you are new to Python itself, work through the Python tutorial first. You do not need to know anything about web development.

Create a virtual environment and install Django

A virtual environment is a private folder of packages for one project. It keeps Django 5.2 for one project from clashing with Django 6.x in another, and it keeps your system Python clean. Always create one.

Terminal
mkdir mysite-workspace
cd mysite-workspace
python -m venv .venv

# Activate it
source .venv/bin/activate        # macOS and Linux
.venv\Scripts\activate           # Windows (Command Prompt or PowerShell)

python -m pip install --upgrade pip
python -m pip install django
python -m django --version

The last command prints the installed version, which proves the install worked. When the environment is active, your prompt starts with (.venv). Run deactivate to leave it.

Record your dependencies with python -m pip freeze > requirements.txt. Anyone (including you in six months, or your server) can recreate the exact environment with python -m pip install -r requirements.txt.

Create the project

A Django project is the folder of configuration for one website. startproject generates it. The final . tells Django to put manage.py in the current folder instead of nesting another directory:

Terminal
django-admin startproject mysite .

django-admin is the tool for creating things before a project exists. After that, you work with the project's own manage.py, which is the same tool pre-wired to your settings.

flowchart LR
    M["manage.py"] -->|"sets DJANGO_SETTINGS_MODULE"| S["mysite/settings.py"]
    S -->|"ROOT_URLCONF"| U["mysite/urls.py"]
    S -->|"INSTALLED_APPS"| A["blog/ (your app)"]
    U --> A
    W["mysite/wsgi.py<br/>mysite/asgi.py"] -->|"reads"| S

manage.py and the server entry points all start from settings.py, which points at the URL configuration and the installed apps.

Generate a project and an app for real

The next example runs Django's own startproject and startapp commands inside your browser. They write into a temporary folder that disappears when the run ends, and the code prints the resulting tree. The command names and layout are identical to what you get on your computer.

Python What startproject and startapp create

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Here is what each generated file is for:

File Purpose
manage.py Command-line entry point for your project (runserver, migrate, test and more).
mysite/settings.py All configuration: installed apps, database, middleware, templates, static files.
mysite/urls.py The root URL configuration (urlpatterns).
mysite/wsgi.py Entry point for WSGI servers such as Gunicorn.
mysite/asgi.py Entry point for ASGI servers such as Uvicorn (needed for async features).
blog/models.py Your database models.
blog/views.py Your views.
blog/admin.py Registers models with the admin site.
blog/apps.py The AppConfig class that describes the app.
blog/migrations/ Generated database migration files.
blog/tests.py A place for tests (later you can turn it into a tests/ package).

On your machine the commands are:

Terminal
python manage.py startapp blog

Creating an app does not activate it. Open mysite/settings.py and add the app's config to INSTALLED_APPS:

Python
INSTALLED_APPS = [
    "django.contrib.admin",
    # ... the other built-in apps ...
    "blog",
]

Run the development server

First apply the built-in migrations, which create the tables for users, sessions and permissions in a new db.sqlite3 file. Then start the server:

Terminal
python manage.py migrate
python manage.py runserver

Open http://127.0.0.1:8000/ in your browser. You will see Django's welcome page (a rocket and "The install worked successfully!"). While DEBUG = True, the server automatically restarts whenever you save a Python file, and error pages show the full traceback with variable values. Press Ctrl+C in the terminal to stop it.

The development server is for development only. It is not hardened or fast enough for real traffic; production uses Gunicorn or Uvicorn behind a proxy, as covered in Deploying Django.

The manage.py commands you will use daily

Command What it does
runserver Starts the development server, with auto-reload.
makemigrations Writes migration files after you change models.
migrate Applies migrations to the database.
createsuperuser Creates an admin account.
shell Opens a Python shell with Django loaded, handy for trying the ORM.
test Runs your test suite.
check Looks for configuration problems (check --deploy audits production settings).
collectstatic Gathers static files into one folder for deployment.
startapp Creates a new app skeleton.

You can list all of them with python manage.py help. Third-party packages and your own code add more.

The same project, in process

Behind the scenes, manage.py does very little: it sets DJANGO_SETTINGS_MODULE to "mysite.settings", calls django.setup(), and dispatches to a command. You can do the same thing from any Python code. The next example builds a working project without any files: it configures settings in code, runs the same check and migrate commands, lists the tables the migration created, and serves one page through the test client.

Python A project without files

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice createsuperuser -> django.contrib.auth: commands belong to the app that provides them, which is why INSTALLED_APPS matters. Add "django.contrib.auth" and createsuperuser exists; remove it and the command disappears.

Your project's files are ordinary Python modules. ROOT_URLCONF = "mysite.urls" is just a dotted import path, which is why a plain types.ModuleType("mysite") can stand in for mysite/urls.py in the examples. This is only a trick for the browser; in a real project always use real files.

Common first-day problems

  • django-admin: command not found: the virtual environment is not active. Activate it, or run python -m django startproject mysite ..
  • ModuleNotFoundError: No module named 'django': you installed Django in a different environment than the one running your command.
  • "You have unapplied migrations": run python manage.py migrate.
  • Port already in use: run python manage.py runserver 8001 to use another port.
  • Your app's pages return 404: you created the app but did not add it to INSTALLED_APPS and urls.py yet. The next lessons cover both.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should you create a virtual environment for each Django project?

    A virtual environment holds a private set of packages. Different projects can use different Django versions without conflicts.
  2. 2. What does the trailing dot in django-admin startproject mysite . do?

    The optional last argument is the target directory. A dot means the current directory, so you avoid the doubled mysite/mysite/ nesting.
  3. 3. Which file lists the apps that are active in your project?

    Only apps listed in INSTALLED_APPS are loaded: their models, templates, migrations and management commands become available.
  4. 4. What is python manage.py runserver suitable for?

    The built-in server is convenient for development but is not designed for production load or security. Use Gunicorn or Uvicorn behind a proxy there.

Summary

  • Create a virtual environment, activate it, and pip install django; check with python -m django --version.
  • django-admin startproject mysite . creates manage.py plus a mysite/ package with settings.py, urls.py, wsgi.py and asgi.py.
  • python manage.py startapp blog creates an app; add it to INSTALLED_APPS to activate it.
  • migrate then runserver gives you a working site at http://127.0.0.1:8000/.
  • manage.py just sets the settings module, calls django.setup() and runs a command; the same can be done in code with settings.configure().
  • The development server is for local use only.

Next lesson: Projects, Apps and Settings.