Python Development Environment Setup – A Cross‑Platform Guide (Windows & Linux)

Step 1: Choose a Python version management tool

On any platform, we strongly recommend using uv (you are already using it). It replaces pyenv + pip + venv in one tool.

Step 2: Windows Environment Setup

2.1 Install uv (version + package management, all‑in‑one)

# PowerShell (as Administrator) – one‑line install
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, the default location is %USERPROFILE%\.local\bin, and it is automatically added to your PATH.

2.2 Install Python runtimes

# Install specific versions (uv automatically downloads pre‑built packages)
uv python install 3.13
uv python install 3.11

# List installed versions
uv python list

Python is installed by default in %USERPROFILE%\AppData\Roaming\uv\python\.

2.3 Create a project virtual environment

# Go to your project directory
cd C:\projects\myapp

# Create a .venv and specify the Python version
uv venv --python 3.13

# Activate (Windows)
.venv\Scripts\activate

# Or run directly with uv, no manual activation needed
uv run python --version

2.4 Install dependencies

# Equivalent to pip install
uv pip install django wagtail

# Install from a requirements file
uv pip install -r requirements.txt

# Freeze dependencies
uv pip freeze > requirements.txt

2.5 Windows‑specific considerations

Step 3: Linux Environment Setup

3.1 Install uv

# One‑line install
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or install via pip (if you already have Python)
pip install uv

Installation path: ~/.local/bin/uv. Restart your shell or run source ~/.bashrc.

3.2 Install build dependencies (one‑time)

# Debian/Ubuntu
sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev curl \
  libncursesw5-dev xz-utils tk-dev libxml2-dev \
  libxmlsec1-dev libffi-dev liblzma-dev

# RHEL/CentOS/Fedora
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y openssl-devel bzip2-devel libffi-devel \
  readline-devel sqlite-devel xz-devel zlib-devel

3.3 Install Python runtimes

# uv automatically downloads pre‑built Python
uv python install 3.13

# Or via pyenv (alternative)
curl https://pyenv.run | bash
pyenv install 3.13.0
pyenv global 3.13.0

3.4 Create a project virtual environment

cd /opt/projects/myapp

# Create virtual environment
uv venv --python 3.13

# Activate
source .venv/bin/activate

# Or run directly with uv
uv run python --version

3.5 Linux‑specific considerations

Step 4: IDE Configuration (Cross‑Platform)

VS Code Configuration

Create .vscode/settings.json in your project root:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  },
  "python.analysis.typeCheckingMode": "basic",
  "mypy-type-checker.args": ["--ignore-missing-imports"]
}

You must install these 4 extensions: Python, Ruff, Mypy Type Checker, and Even Better TOML.

PyCharm Configuration

Go to Settings → Project → Python Interpreter → Add Local Interpreter → select .venv/bin/python.

Step 5: Verify Your Environment

(No content was provided under this heading in the original; the author presumably expects you to run the commands from the previous steps to confirm everything works.)

Summary – Three Golden Rules

1. Use uv to manage everything – it replaces pip, venv, and pyenv at the same time. The commands are identical on Windows and Linux, so there is zero mental overhead.
2. One .venv per project – this is the principle of isolation. Never pollute the global Python installation.
3. The biggest pitfall on Windows is C extension compilation – install Visual Studio Build Tools or use WSL2 to avoid it entirely.

Your situation (Windows + Django + uv) is already almost ready. Go through the verification checklist and you’ll be set. If you run into any project‑specific environment errors, feel free to paste them here for help.