Django Environment and Installation

Introduction

Before you create a project or run manage.py, you need Python 3.10+, an isolated virtual environment, and Django 5 installed into that environment—not globally on the system Python. This chapter verifies Python, creates a venv, installs Django, sets up an editor, and prepares a .gitignore and requirements.txt so later chapters start from a reproducible baseline.

Prerequisites

• What Is Django
• Python installed — see Python on Windows, macOS, or Linux
• Terminal or PowerShell access
• Internet access for PyPI downloads

Version Requirements

Django 5.x supports the Python versions listed on the official download page. Use 3.10+ to match this track and the Python tutorials.

Step 1: Verify Python

python --version
python -m pip --version

On some systems use python3 instead of python:

python3 --version
python3 -m pip --version

Expected: Python 3.10.x or newer.

Windows if python is missing:

py -3 --version

Code explanation:

• python -m pip ensures pip runs for the same interpreter you will use for Django
• If multiple Python versions exist, always activate venv before installing Django (next step)

Step 2: Create a Workspace Folder

mkdir hello-django
cd hello-django

This directory will hold the venv and (in the next chapter) your Django project files.

Step 3: Create and Activate a Virtual Environment

Windows (PowerShell or CMD)

python -m venv .venv
.venv\Scripts\activate

Prompt should show (.venv) at the start of the line.

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate

Deactivate anytime:

deactivate

Code explanation:

• .venv/ lives inside the project folder (name is convention; .venv is common)
• After activation, python and pip point inside .venv/
• Re-run activate in every new terminal session before working on the project

More detail: pip and venv patterns.

Step 4: Upgrade pip and Install Django

With venv activated:

python -m pip install -U pip
python -m pip install "Django>=5.0,<6"

Pin for teams (optional, after install):

python -m pip freeze | findstr Django    # Windows
python -m pip freeze | grep Django     # macOS/Linux

Example line in requirements.txt:

Django==5.1.7

Create initial requirements file:

python -m pip freeze > requirements.txt

Code explanation:

• Django>=5.0,<6 keeps you on Django 5.x without accidentally pulling Django 6 when it exists
• requirements.txt lets others run pip install -r requirements.txt for the same versions

Step 5: Verify Django Installation

python -m django --version
python -c "import django; print(django.get_version())"

Expected: 5.0.x or 5.1.x (or newer 5.x).

Quick sanity check that management commands exist:

python -m django help

You should see subcommands like startproject, runserver, migrate (used starting in the next chapter).

Editor Setup

VS Code

1. Open the hello-django folder
2. Install extensions: Python (Microsoft), Django (optional syntax/templates)
3. Python: Select Interpreter → choose .venv/Scripts/python.exe (Windows) or .venv/bin/python (macOS/Linux)

PyCharm

1. Open → select hello-django
2. Settings → Project → Python Interpreter → Add → Existing → point to .venv
3. PyCharm Professional has built-in Django support; Community works fine with the Python plugin

Code explanation:

• Wrong interpreter = packages installed in venv but IDE runs system Python → import errors
• After changing interpreter, restart the terminal inside the IDE if imports fail

.gitignore for Django Projects

Create hello-django/.gitignore (project root, next to .venv):

See also Git .gitignore.

Optional: django-extensions (Later)

Not required now. Some teams install:

python -m pip install django-extensions

Provides shell_plus, runserver_plus, etc. This track mentions it only as optional tooling.

Optional: uv or pip-tools

Hello Code documents pip and uv. For Django learning, venv + pip is enough. Switch to uv when your team standardizes on it—the venv workflow stays the same.

Common Install Problems

Verify which Python pip uses:

python -c "import sys; print(sys.executable)"

Path should include .venv.

Post-Install Checklist

• python --version shows 3.10+
• .venv created and activated ((.venv) in prompt)
• python -m pip install "Django>=5.0,<6" succeeded
• python -m django --version prints 5.x
• IDE interpreter set to .venv
• .gitignore and requirements.txt in project root

FAQ

python vs python3?

On macOS/Linux, use whichever maps to 3.10+ after venv activation—usually both work inside .venv. Outside venv, python3 is often explicit.

Do I need Docker for learning?

No. Local venv is enough until the Docker deploy chapter.

Can I use Conda instead of venv?

Yes. Create a Conda env with Python 3.10+, then pip install Django. See Conda in Python.

WSL2 on Windows?

Create venv inside WSL (Linux steps). Run Django on 127.0.0.1:8000; browse from Windows at the same address.

Install Django in PyCharm wizard?

Fine for quick tests; this track uses terminal + venv so commands match production and CI docs.

Why pin Django>=5.0,<6?

Keeps tutorials aligned with Django 5 APIs. Adjust upper bound when your team upgrades major versions deliberately.