垦荒学园

English

简体中文

English

简体中文

Toggle theme

Development Environment Setup ​

This chapter details how to set up a Django development environment, including Python installation, virtual environment configuration, Django installation, and the selection and configuration of development tools.

System Requirements ​

Operating System Support ​

Django supports the following operating systems:

  • Windows 10/11
  • macOS 10.15+
  • Linux (Ubuntu, CentOS, Debian, etc.)

Python Version Requirements ​

python
# Python versions supported by Django 4.2 LTS
Python 3.8+   # Minimum requirement
Python 3.9    # Recommended
Python 3.10   # Recommended
Python 3.11   # Recommended
Python 3.12   # Latest supported

Python Installation ​

Windows System ​

1. Download Python from the Official Website ​

Visit the Python website to download the latest version:

bash
# Download URL
https://www.python.org/downloads/windows/

# Recommended download
Python 3.11.x (stable)

2. Install Python ​

bash
# Installation options
☑ Add Python to PATH
☑ Install for all users
☑ Associate files with Python
☑ Create shortcuts for installed applications
☑ Add Python to environment variables
☑ Precompile standard library

3. Verify Installation ​

cmd
# Open Command Prompt
python --version
# Output: Python 3.11.x

pip --version
# Output: pip 23.x.x from ...

macOS System ​

1. Install Using Homebrew (Recommended) ​

bash
# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python@3.11

# Verify installation
python3 --version
pip3 --version

2. Install from Official Website ​

bash
# Download URL
https://www.python.org/downloads/macos/

# Verify after installation
python3 --version
pip3 --version

Linux System ​

Ubuntu/Debian ​

bash
# Update package list
sudo apt update

# Install Python 3.11
sudo apt install python3.11 python3.11-pip python3.11-venv

# Verify installation
python3.11 --version
pip3 --version

CentOS/RHEL ​

bash
# Install EPEL repository
sudo yum install epel-release

# Install Python 3.11
sudo yum install python311 python311-pip

# Verify installation
python3.11 --version
pip3 --version

Virtual Environment Configuration ​

Virtual environments are a best practice in Python development, allowing the creation of isolated Python environments for each project.

Why Use Virtual Environments ​

python
# Problem scenario: Different projects require different package versions
Project A: Django==3.2.0, requests==2.25.0
Project B: Django==4.2.0, requests==2.28.0

# Solution: Create separate virtual environments for each project
venv_project_a/
├── Django==3.2.0
└── requests==2.25.0

venv_project_b/
├── Django==4.2.0
└── requests==2.28.0

Creating Virtual Environments Using venv ​

1. Create a Virtual Environment ​

bash
# Windows
python -m venv django_env

# macOS/Linux
python3 -m venv django_env

2. Activate the Virtual Environment ​

bash
# Windows
django_env\Scripts\activate

# macOS/Linux
source django_env/bin/activate

# Command prompt will show after activation
(django_env) C:\Users\YourName>

3. Deactivate the Virtual Environment ​

bash
# Any system
deactivate

Creating Virtual Environments Using conda ​

If you use Anaconda or Miniconda:

bash
# Create a virtual environment
conda create -n django_env python=3.11

# Activate the environment
conda activate django_env

# Deactivate the environment
conda deactivate

# List all environments
conda env list

# Remove an environment
conda env remove -n django_env

Virtual Environment Best Practices ​

bash
# 1. Create separate virtual environments for each project
mkdir my_django_project
cd my_django_project
python -m venv venv

# 2. Use meaningful environment names
python -m venv blog_project_env
python -m venv ecommerce_env

# 3. Add virtual environment directories to .gitignore
echo "venv/" >> .gitignore
echo "*.pyc" >> .gitignore
echo "__pycache__/" >> .gitignore

# 4. Create requirements.txt to record dependencies
pip freeze > requirements.txt

# 5. Install dependencies from requirements.txt
pip install -r requirements.txt

Django Installation ​

Install Django ​

bash
# Ensure the virtual environment is activated
(django_env) $ pip install Django

# Install a specific version
(django_env) $ pip install Django==4.2.7

# Install the latest LTS version
(django_env) $ pip install "Django>=4.2,<5.0"

Verify Django Installation ​

bash
# Check Django version
(django_env) $ python -m django --version
# Output: 4.2.7

# Or check within Python
(django_env) $ python
>>> import django
>>> django.get_version()
'4.2.7'
>>> django.VERSION
(4, 2, 7, 'final', 0)

Install Additional Dependencies ​

bash
# Database drivers
pip install psycopg2-binary  # PostgreSQL
pip install mysqlclient      # MySQL
pip install cx_Oracle        # Oracle

# Image processing
pip install Pillow

# Development tools
pip install django-debug-toolbar
pip install django-extensions

# API development
pip install djangorestframework

# Create a complete requirements.txt
pip freeze > requirements.txt

Development Tool Selection ​

Code Editors/IDEs ​

1. Visual Studio Code (Recommended) ​

json
// .vscode/settings.json
{
    "python.defaultInterpreterPath": "./venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "black",
    "python.formatting.blackArgs": ["--line-length=88"],
    "files.associations": {
        "*.html": "django-html"
    },
    "emmet.includeLanguages": {
        "django-html": "html"
    }
}

Recommended extensions:

json
// .vscode/extensions.json
{
    "recommendations": [
        "ms-python.python",
        "ms-python.flake8",
        "ms-python.black-formatter",
        "batisteo.vscode-django",
        "wholroyd.jinja",
        "bradlc.vscode-tailwindcss"
    ]
}

2. PyCharm Professional ​

python
# PyCharm configuration
# File -> Settings -> Project -> Python Interpreter
# Select the Python interpreter in the virtual environment

# Django support
# File -> Settings -> Languages & Frameworks -> Django
# Enable Django Support: ✓
# Django project root: /path/to/your/project
# Settings: settings.py

3. Sublime Text ​

json
// Packages/User/Python.sublime-settings
{
    "python_interpreter": "/path/to/venv/bin/python",
    "suppress_word_completions": true,
    "suppress_explicit_completions": true
}

Database Tools ​

1. SQLite Browser ​

bash
# Install SQLite Browser
# Windows: Download installer
# macOS: brew install --cask db-browser-for-sqlite
# Ubuntu: sudo apt install sqlitebrowser

2. pgAdmin (PostgreSQL) ​

bash
# Install pgAdmin
# Visit https://www.pgadmin.org/download/

3. MySQL Workbench ​

bash
# Install MySQL Workbench
# Visit https://www.mysql.com/products/workbench/

Version Control ​

Git Configuration ​

bash
# Install Git
# Windows: https://git-scm.com/download/win
# macOS: brew install git
# Linux: sudo apt install git

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Create .gitignore file
cat > .gitignore << EOF
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
ENV/

# Django
*.log
local_settings.py
db.sqlite3
media/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db
EOF

Project Structure Best Practices ​

my_django_project/
├── venv/                   # Virtual environment
├── requirements/           # Dependency files
│   ├── base.txt           # Base dependencies
│   ├── development.txt    # Development dependencies
│   └── production.txt     # Production dependencies
├── config/                # Configuration files
│   ├── __init__.py
│   ├── settings/
│   │   ├── __init__.py
│   │   ├── base.py        # Base settings
│   │   ├── development.py # Development settings
│   │   └── production.py  # Production settings
│   ├── urls.py
│   └── wsgi.py
├── apps/                  # Application directory
│   ├── __init__.py
│   ├── accounts/          # User account app
│   ├── blog/              # Blog app
│   └── core/              # Core app
├── static/                # Static files
├── media/                 # Media files
├── templates/             # Template files
├── locale/                # Internationalization files
├── tests/                 # Test files
├── docs/                  # Documentation
├── scripts/               # Script files
├── .env                   # Environment variables
├── .gitignore
├── manage.py
├── README.md
└── requirements.txt

Environment Variable Configuration ​

1. Install python-decouple ​

bash
pip install python-decouple

2. Create .env file ​

bash
# .env
DEBUG=True
SECRET_KEY=your-secret-key-here
DATABASE_URL=sqlite:///db.sqlite3
ALLOWED_HOSTS=localhost,127.0.0.1

# Database configuration
DB_NAME=mydatabase
DB_USER=myuser
DB_PASSWORD=mypassword
DB_HOST=localhost
DB_PORT=5432

# Email configuration
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password

3. Use in settings.py ​

python
# settings.py
from decouple import config
import os

# Base configuration
DEBUG = config('DEBUG', default=False, cast=bool)
SECRET_KEY = config('SECRET_KEY')
ALLOWED_HOSTS = config('ALLOWED_HOSTS', default='').split(',')

# Database configuration
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': config('DB_NAME'),
        'USER': config('DB_USER'),
        'PASSWORD': config('DB_PASSWORD'),
        'HOST': config('DB_HOST', default='localhost'),
        'PORT': config('DB_PORT', default='5432'),
    }
}

# Email configuration
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = config('EMAIL_HOST')
EMAIL_PORT = config('EMAIL_PORT', cast=int)
EMAIL_USE_TLS = True
EMAIL_HOST_USER = config('EMAIL_HOST_USER')
EMAIL_HOST_PASSWORD = config('EMAIL_HOST_PASSWORD')

Development Tool Configuration ​

Django Debug Toolbar ​

bash
# Install
pip install django-debug-toolbar
python
# settings.py
INSTALLED_APPS = [
    # ...
    'debug_toolbar',
]

MIDDLEWARE = [
    # ...
    'debug_toolbar.middleware.DebugToolbarMiddleware',
]

# Show only in DEBUG mode
INTERNAL_IPS = [
    '127.0.0.1',
]

# Configure panels
DEBUG_TOOLBAR_PANELS = [
    'debug_toolbar.panels.versions.VersionsPanel',
    'debug_toolbar.panels.timer.TimerPanel',
    'debug_toolbar.panels.settings.SettingsPanel',
    'debug_toolbar.panels.headers.HeadersPanel',
    'debug_toolbar.panels.request.RequestPanel',
    'debug_toolbar.panels.sql.SQLPanel',
    'debug_toolbar.panels.staticfiles.StaticFilesPanel',
    'debug_toolbar.panels.templates.TemplatesPanel',
    'debug_toolbar.panels.cache.CachePanel',
    'debug_toolbar.panels.signals.SignalsPanel',
    'debug_toolbar.panels.logging.LoggingPanel',
    'debug_toolbar.panels.redirects.RedirectsPanel',
    'debug_toolbar.panels.profiling.ProfilingPanel',
]
python
# urls.py
from django.conf import settings
from django.conf.urls import include

if settings.DEBUG:
    import debug_toolbar
    urlpatterns = [
        path('__debug__/', include(debug_toolbar.urls)),
    ] + urlpatterns

Django Extensions ​

bash
# Install
pip install django-extensions
python
# settings.py
INSTALLED_APPS = [
    # ...
    'django_extensions',
]
bash
# Useful commands
python manage.py shell_plus          # Enhanced shell
python manage.py show_urls           # Show all URLs
python manage.py validate_templates  # Validate templates
python manage.py runserver_plus      # Enhanced development server

Code Quality Tools ​

1. Black (Code Formatter) ​

bash
# Install
pip install black

# Use
black .
black --line-length 88 .
black --check .  # Check without modifying
toml
# pyproject.toml
[tool.black]
line-length = 88
target-version = ['py38']
include = '\.pyi?$'
extend-exclude = '''
/(
  # directories
  \.eggs
  | \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | build
  | dist
)/
'''

2. Flake8 (Code Linter) ​

bash
# Install
pip install flake8

# Use
flake8 .
ini
# .flake8
[flake8]
max-line-length = 88
exclude =
    .git,
    __pycache__,
    venv,
    migrations
ignore =
    E203,  # whitespace before ':'
    W503,  # line break before binary operator

3. isort (Import Sorter) ​

bash
# Install
pip install isort

# Use
isort .
isort --check-only .  # Check without modifying
toml
# pyproject.toml
[tool.isort]
profile = "black"
multi_line_output = 3
line_length = 88

Pre-commit Hooks ​

bash
# Install pre-commit
pip install pre-commit

# Create configuration file
cat > .pre-commit-config.yaml << EOF
repos:
  - repo: https://github.com/psf/black
    rev: 23.9.1
    hooks:
      - id: black
        language_version: python3.11

  - repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
      - id: isort
        args: ["--profile", "black"]

  - repo: https://github.com/pycqa/flake8
    rev: 6.1.0
    hooks:
      - id: flake8

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
EOF

# Install hooks
pre-commit install

Verify Environment Configuration ​

Create a Test Project ​

bash
# Activate virtual environment
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Create Django project
django-admin startproject testproject
cd testproject

# Run development server
python manage.py runserver

# Visit http://127.0.0.1:8000/
# Should see Django welcome page

Environment Checklist ​

python
# check_environment.py
import sys
import django
from django.conf import settings

def check_environment():
    print("=== Django Environment Check ===")
    
    # Python version
    print(f"Python version: {sys.version}")
    
    # Django version
    print(f"Django version: {django.get_version()}")
    
    # Virtual environment check
    if hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix):
        print("✓ Virtual environment activated")
    else:
        print("✗ Virtual environment not activated")
    
    # Installed packages
    import pkg_resources
    installed_packages = [d.project_name for d in pkg_resources.working_set]
    
    required_packages = ['django', 'pillow']
    for package in required_packages:
        if package.lower() in [p.lower() for p in installed_packages]:
            print(f"✓ {package} installed")
        else:
            print(f"✗ {package} not installed")

if __name__ == "__main__":
    check_environment()

Common Issue Resolution ​

1. Python Command Not Recognized ​

bash
# Windows
# Ensure Python is added to PATH environment variable
# Or use py command
py --version
py -m pip install django

# macOS/Linux
# Use python3 command
python3 --version
python3 -m pip install django

2. pip Installation Fails ​

bash
# Upgrade pip
python -m pip install --upgrade pip

# Use domestic mirror
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple django

# Configure permanent mirror source
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

3. Virtual Environment Activation Fails ​

bash
# Windows PowerShell execution policy issue
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or use cmd instead of PowerShell

4. Django Import Error ​

python
# Ensure in the correct virtual environment
which python  # Linux/macOS
where python  # Windows

# Check if Django is in Python path
python -c "import django; print(django.__file__)"

Chapter Summary ​

This chapter detailed the setup of a Django development environment:

Key Points:

  • Python Installation: Choose the appropriate Python version
  • Virtual Environment: Create isolated environments for each project
  • Django Installation: Install Django using pip
  • Development Tools: Select appropriate IDEs and extensions
  • Project Structure: Organize code following best practices

Best Practices:

  • Use virtual environments to isolate project dependencies
  • Configure environment variables to manage sensitive information
  • Use code quality tools to ensure code standards
  • Set up pre-commit hooks for automatic code checking
  • Create detailed requirements.txt

Development Toolchain:

  • VS Code + Python extension
  • Django Debug Toolbar
  • Black + Flake8 + isort
  • Git version control
  • Virtual environment management

In the next chapter, we will create our first Django project and learn about the basic project structure and configuration of Django.

Further Reading ​

Content is for learning and research only.

Copyright 2026 Kenhuang Academy. All Rights Reserved. About