Setting Up: Python 3.13, uv & the Modern Toolchain¶

Estimated time: 20 min read · Part: Why Python, and How It Runs

Getting the environment right is not busywork — a tangled Python setup is the single most common reason a beginner's code "works on my machine" and nowhere else. In 2026 the tooling has consolidated dramatically around one fast tool, uv, so the modern path is simpler than the historical mess of pip, virtualenv, pyenv, and poetry all at once. Even so, you will encounter those older tools in real codebases, so knowing both the new way and its predecessors is necessary.

uv: the tool that replaced the toolbox¶

uv (from Astral, the makers of the Ruff linter) is a single Rust-built binary that installs Python itself, creates virtual environments, resolves and installs dependencies, and locks them — doing in seconds what older tools did in minutes. It is 10–100x faster than pip for dependency resolution, and its lockfile (uv.lock) is deterministic: the same lockfile produces byte-identical environments on every machine, critical for reproducible demos and CI pipelines.

The design principle behind uv is "one tool, one interface." Before uv, a typical project setup required: pyenv to install the right Python version, venv to create the environment, pip to install packages, and optionally poetry or pip-tools to manage a lockfile. Each tool had its own configuration, its own bugs, and its own upgrade path. uv replaces all of them with a single coherent interface.

# ── 1. Install uv (macOS / Linux) ──────────────────────────────────
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell):
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# ── 2. Install a specific Python version ───────────────────────────
uv python install 3.13

# ── 3. Start a new project ─────────────────────────────────────────
uv init my-analysis          # creates directory, pyproject.toml, .python-version
cd my-analysis

# ── 4. Add dependencies ────────────────────────────────────────────
uv add pandas httpx           # resolves + installs + writes to pyproject.toml + lockfile

# ── 5. Run your script ─────────────────────────────────────────────
uv run main.py                # uses the project's managed venv automatically

Anatomy of a modern project¶

Running uv init my-analysis generates a small but complete project structure. Understanding each file is essential — you'll read and write these on every real project.

  my-analysis/
  ├── pyproject.toml      ← project metadata + dependencies (human-editable)
  ├── uv.lock             ← exact resolved versions of every package (committed to git)
  ├── .python-version     ← the Python version this project uses (e.g. "3.13")
  ├── .venv/              ← the virtual environment (git-ignored, rebuilt from lock)
  │   ├── bin/python      ← the Python interpreter for this project
  │   └── lib/...         ← installed packages
  └── main.py             ← starter script

[project]
name = "my-analysis"
version = "0.1.0"
requires-python = ">=3.13"    # minimum Python version
dependencies = [
    "pandas>=2.2",            # added by `uv add pandas`
    "httpx>=0.27",
]

[tool.uv]
# uv-specific settings (dev dependencies, source overrides, etc.)

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

The key distinction is between pyproject.toml (which records your constraints — "pandas 2.x or higher") and uv.lock (which records the exact resolved version — "pandas 2.2.3"). You commit both to git. A new team member runs uv sync and gets an identical environment in seconds, regardless of what newer package versions have shipped since you wrote the code.

# Add a production dependency:
uv add requests

# Add a development-only dependency (not shipped in production):
uv add --dev pytest ruff mypy

# Remove a dependency:
uv remove requests

# Sync environment to match lockfile (e.g. after a git pull):
uv sync

# Run a one-off script with temporary dependencies (no project needed):
uv run --with pandas python -c "import pandas; print(pandas.__version__)"

# Show the resolved dependency tree:
uv tree

# Update a specific package to the latest compatible version:
uv lock --upgrade-package pandas

The classic tools you must still recognise¶

Any codebase over two years old almost certainly uses some combination of the older toolchain. You'll encounter requirements.txt files, Pipfiles, and setup.py files in existing repositories. Recognising these and knowing how to work with them — and when to propose migrating to uv — is a real professional skill.

Editor and IDE setup¶

The dominant editors for Python in 2026 are VS Code (with the Pylance extension) and PyCharm (JetBrains' dedicated Python IDE). Both support uv-managed environments automatically. The key extensions you want in VS Code: Python (Microsoft), Pylance (type checking, autocomplete), Ruff (linting + formatting), and optionally a Jupyter extension if you work with notebooks.

# Ruff is the 2026 standard linter AND formatter (replaces flake8 + black + isort)
uv add --dev ruff

# Check for issues:
ruff check .

# Auto-fix what can be fixed:
ruff check --fix .

# Format code (replaces black):
ruff format .

# The ruff config goes in pyproject.toml:
# [tool.ruff]
# line-length = 88
# select = ["E", "F", "I"]  # pycodestyle, pyflakes, isort

# Terminal:
# uv init deal-probe
# cd deal-probe
# uv add httpx rich
# (then write main.py:)

import httpx
from rich.console import Console
from rich.table import Table

ENDPOINTS = [
    "https://httpbin.org/get",
    "https://httpbin.org/status/200",
    "https://httpbin.org/status/500",
]

table = Table(title="Endpoint Probe")
table.add_column("URL", style="cyan")
table.add_column("Status", justify="right")
table.add_column("Latency (ms)", justify="right")

for url in ENDPOINTS:
    try:
        r = httpx.get(url, timeout=5)
        ms = f"{r.elapsed.total_seconds() * 1000:.0f}"
        color = "green" if r.is_success else "red"
        table.add_row(url, f"[{color}]{r.status_code}[/{color}]", ms)
    except Exception as e:
        table.add_row(url, "[red]ERROR[/red]", str(e))

Console().print(table)

# Run: uv run main.py
# Inspect lockfile: grep -A5 'name = "httpx"' uv.lock