Python Version Selection¶

Choosing the right Python version is crucial for performance, security, and long-term maintainability.

Recommendation¶

For New Projects (2025)

Use Python 3.13+ for all new projects starting in 2025.

For Existing Projects

Python 3.11+ → Stay current, upgrade when convenient
Python 3.10 → Plan upgrade to 3.13 within 6 months
Python 3.9 or older → Upgrade urgently (security risk)

Python Version Timeline¶

gantt
    title Python Version Support Timeline
    dateFormat YYYY-MM
    section Active
    Python 3.13 :2024-10, 2029-10
    Python 3.12 :2023-10, 2028-10
    Python 3.11 :2022-10, 2027-10
    section EOL
    Python 3.10 :2021-10, 2026-10
    Python 3.9  :2020-10, 2025-10
    Python 3.8  :crit, 2019-10, 2024-10
    Python 3.7  :crit, 2018-06, 2023-06
    Python 3.6  :crit, 2016-12, 2021-12

Python 3.13 Features (October 2024)¶

Performance Improvements¶

15-20% faster than Python 3.10
Improved JIT compiler (experimental)
Better memory management
Faster startup time

Language Features¶

Improved error messages: Even clearer than 3.11
Better type hints: More expressive typing
Enhanced debugging: Better tracebacks

Why Upgrade?¶

PerformanceDeveloper ExperienceType Hints

# Python 3.13 improvements
# - Faster dictionary operations
# - Optimized function calls
# - Better memory locality

# Benchmark example (3.13 vs 3.10):
# Dictionary iteration: 20% faster
# Function calls: 10% faster
# String operations: 15% faster

# Better error messages
# Python 3.13 tells you exactly what's wrong:

user = {"name": "Bob"}
print(user["age"])
# KeyError: 'age'
# Did you mean: 'name'?

# More precise locations in errors
# Points to exact character position

# Python 3.13 type improvements
from typing import override

class Base:
    def method(self) -> str:
        return "base"

class Derived(Base):
    @override
    def method(self) -> str:  # Type checker verifies
        return "derived"

Version Selection Decision Tree¶

See the Decision Trees page for the full decision tree.

Managing Python Versions¶

Using pyenv (Recommended)¶

# Install pyenv
curl https://pyenv.run | bash

# Install Python 3.13.5
pyenv install 3.13.5

# Set global default
pyenv global 3.13.5

# Set project-specific version
cd /path/to/project
pyenv local 3.13.5
# Creates .python-version file

Using asdf¶

# Install asdf
git clone https://github.com/asdf-vm/asdf.git ~/.asdf

# Install Python plugin
asdf plugin add python

# Install Python 3.13.5
asdf install python 3.13.5

# Set project version
asdf local python 3.13.5

Using Docker¶

# Use official Python image
FROM python:3.13.5-slim

# Or use specific variant
FROM python:3.13.5-alpine

Version Pinning Best Practices¶

.python-version File¶

Always create a .python-version file:

# In project root
echo "3.13.5" > .python-version

This ensures: - Consistent versions across team - pyenv/asdf automatically activate correct version - Clear documentation of requirements

pyproject.toml¶

Specify minimum version:

[project]
requires-python = ">=3.13"

Dockerfile¶

Pin exact version:

FROM python:3.13.5-slim
# Not: FROM python:3.13
# Not: FROM python:3

Upgrade Strategy¶

For New Projects¶

✅ Start with Python 3.13+
✅ Pin exact version in .python-version
✅ Document in README

For Existing Projects¶

Step 1: Assess Compatibility¶

# Check dependencies
pip list --outdated

# Check for deprecated features
python -Wd manage.py check

Step 2: Update Dependencies¶

# Update to latest compatible versions
uv pip compile --upgrade requirements.in

# Test thoroughly
pytest

Step 3: Update Python¶

# Install new version
pyenv install 3.13.5

# Switch project
pyenv local 3.13.5

# Recreate virtual environment
rm -rf .venv
uv venv
uv pip sync requirements.txt

Step 4: Test Everything¶

# Run all tests
pytest

# Check for warnings
python -Wd manage.py check --deploy

# Manual testing
# Test critical paths

Step 5: Update CI/CD¶

# .github/workflows/ci.yml
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.13.5'

Version-Specific Considerations¶

Python 3.13¶

Pros: - Fastest Python yet - Latest features - Best error messages - Long support timeline (until 2029)

Cons: - Some libraries may not have wheels yet - Teams may need time to learn new features

Recommendation: ✅ Use for all new projects

Python 3.12¶

Pros: - Stable and fast - Excellent library support - Type hint improvements - F-strings can contain expressions

Cons: - Not as fast as 3.13 - Missing latest features

Recommendation: ✅ Good alternative if 3.13 has library issues

Python 3.11¶

Pros: - Major performance improvement over 3.10 - Excellent error messages - Wide library support - Exception groups

Cons: - Slower than 3.12/3.13

Recommendation: ✅ Acceptable for existing projects

Python 3.10 and Older¶

Cons: - Significantly slower - Approaching EOL - Missing modern features

Recommendation: ⚠️ Upgrade as soon as possible

Common Issues and Solutions¶

Library Compatibility¶

Problem: Library doesn't have Python 3.13 wheels

Solution:

# Option 1: Build from source
pip install --no-binary :all: problematic-package

# Option 2: Use Python 3.12 temporarily
pyenv local 3.12.7

# Option 3: File issue with library maintainer

CI/CD Configuration¶

Problem: CI doesn't support Python 3.13 yet