Python Virtual Environments — Django 1.11 & 4.0 Conflict

You clone a repo, run pip install, and suddenly your Django 3 project breaks because your system has Django 5. That’s what happens without virtual environments. They isolate project dependencies so each app gets exactly the packages it needs, and your global Python stays clean and stable.

Why Python Virtual Environments Are Non-Negotiable

A Python virtual environment is an isolated directory that contains its own Python interpreter, site-packages, and scripts. The core mechanic: it modifies the sys.path so that import statements resolve to packages installed inside that environment, not the global system Python. This prevents the classic 'Django 1.11 vs 4.0' conflict where two projects on the same machine require different major versions of the same library.

Each environment is a self-contained copy of the Python binary plus a lib/pythonX.Y/site-packages/ folder. When you activate it, your shell's PATH is prepended with the environment's bin/ directory, making python and pip point to the local versions. Deactivation restores the original PATH. No magic — just careful path manipulation.

Use a virtual environment for every project, without exception. In production, you'll typically recreate environments from a requirements.txt or Pipfile.lock inside a Docker container. The rule: one environment per project, never share between projects, and never install project dependencies globally. This eliminates version conflicts and makes builds reproducible.

Why Global Package Installation Is a Ticking Time Bomb

When you first install Python and run pip install requests, that library lands in a single global location on your computer. Every Python script you ever write shares that same copy. Sounds convenient — until it isn't.

Picture this: your first project uses requests version 2.20. Six months later you start a new project that needs requests version 2.31 because it uses a feature that didn't exist before. You upgrade globally. Your old project breaks. You downgrade to fix the old project. The new project breaks. You're stuck in a loop with no clean way out.

This exact scenario has a name in software: dependency conflict. It's not hypothetical — it's the single most common source of pain for Python beginners and professionals alike.

Virtual environments break this cycle permanently. Each environment is a self-contained folder that holds its own Python interpreter and its own set of packages. Project A's requests 2.20 and Project B's requests 2.31 can coexist peacefully on the same machine because they live in completely different folders and never meet.

Here's a subtle but important detail: virtual environments don't copy the entire Python installation. They create symlinks (Mac/Linux) or shortcuts (Windows) to the Python binary and then add their own site-packages folder. This keeps environments lightweight — typically 10-20 MB plus whatever packages you install.

import sys
import site

# This script shows you WHERE Python is currently looking for packages.
# Run this BEFORE creating a virtual environment to see the global setup.
# Then run it again AFTER activating one — the paths will be completely different.

print("=== Python Executable Location ===")
# This tells you WHICH python binary is currently running this script
print(f"Python binary: {sys.executable}")

print("\n=== Where Python Looks for Installed Packages ===")
# sys.path is the list of folders Python searches when you write 'import something'
for index, path in enumerate(sys.path):
    print(f"  [{index}] {path}")

print("\n=== Site-packages Directory (where pip installs things) ===")
# site.getsitepackages() returns the folders where pip drops installed libraries
for packages_dir in site.getsitepackages():
    print(f"  {packages_dir}")

print("\n=== Are we in a virtual environment? ===")
# sys.prefix is the base directory of the Python installation
# In a venv, sys.prefix points to the .venv folder, not the system Python
if hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix):
    print(f"  ✓ Active virtual environment detected at: {sys.prefix}")
else:
    print("  ✗ No virtual environment active — running in global Python")

Creating and Activating Your First Virtual Environment

Python ships with a built-in module called venv (short for virtual environment). You don't need to install anything — it's already there, waiting. You create a virtual environment with a single terminal command, and from that moment on, that folder is your project's private kitchen.

The general pattern is: python -m venv <name-of-environment>. The name is just a folder name — most developers use venv or .venv (with a dot prefix so the folder is hidden by default on Mac/Linux).

Once created, you need to activate it. Activating tells your terminal 'for every command I run from now on, use the Python and pip inside this folder, not the global ones'. The activation command is slightly different depending on your operating system, but the effect is identical.

After activation your terminal prompt usually changes to show the environment name in parentheses — that's your visual confirmation that you're inside the bubble. When you're done working, deactivate drops you back to the global environment.

What's actually happening when you activate? The activation script modifies your shell's PATH environment variable, adding the .venv/bin directory to the front. Since shells search PATH in order, python now resolves to .venv/bin/python first. The VIRTUAL_ENV environment variable is also set so tools can detect which environment is active. The deactivate command restores the original PATH.

#!/bin/bash
# ── STEP 1: Create a project folder and move into it ──────────────────────────
mkdir my_weather_app
cd my_weather_app

# ── STEP 2: Create the virtual environment ────────────────────────────────────
# 'python -m venv' tells Python to run the built-in venv module
# '.venv' is the name of the folder that will hold the environment
# Using a dot prefix (.venv) keeps it hidden from casual 'ls' listings
python -m venv .venv

# You'll now see a .venv folder. Peek inside — it's just files:
# .venv/
#   bin/          ← Python binary and activation scripts (Mac/Linux)
#   lib/          ← Where pip will install packages FOR THIS PROJECT ONLY
#   pyvenv.cfg    ← Config file pointing back to the original Python

# ── STEP 3: Activate the environment ──────────────────────────────────────────

# On macOS / Linux:
source .venv/bin/activate

# On Windows (Command Prompt):
# .venv\Scripts\activate.bat

# On Windows (PowerShell):
# .venv\Scripts\Activate.ps1

# ── STEP 4: Confirm the environment is active ─────────────────────────────────
# Your prompt should now show (.venv) at the start, like:
# (.venv) user@machine:~/my_weather_app$

# Double-check by asking WHICH python is active:
which python          # Mac/Linux
# Should print: /path/to/my_weather_app/.venv/bin/python
# (NOT /usr/local/bin/python3 — that's the global one)

# Check that pip also points to the environment:
which pip
# Should print: /path/to/my_weather_app/.venv/bin/pip

# ── STEP 5: Install a package INSIDE the environment ──────────────────────────
# This installs 'requests' ONLY for this project, not globally
pip install requests

# ── STEP 6: Deactivate when you're done working ───────────────────────────────
deactivate
# Prompt returns to normal — you're back in the global environment

# ── STEP 7: See the difference ────────────────────────────────────────────────
echo "\n=== PATH before activation ==="
echo $PATH | tr ':' '\n' | head -5

echo "\n=== PATH after activation (run this inside the activated env) ==="
# source .venv/bin/activate
# echo $PATH | tr ':' '\n' | head -5
# Notice .venv/bin appears at the FRONT of PATH

Freezing Dependencies So Your Team Gets Identical Setups

Stop relying on pip list for reproducibility. pip list shows installed packages including those from the system or editable installs — it's a mess. pip freeze outputs only packages installed via pip in the exact format pip needs to reinstall them: package==version. That's what goes into requirements.txt. Period.

But pinning everything with == creates the pinning problem: your requirements.txt locks every transitive dependency, making upgrades a nightmare. You don't know which deps are direct vs indirect. Enter pip-compile from pip-tools. Create a requirements.in file listing only your direct dependencies (e.g., requests>=2.31.0). Run pip-compile requirements.in to generate requirements.txt with all transitive deps pinned. Devs edit .in, CI uses .txt. Workflow: pip-compile --upgrade-package requests to bump just one dep without blowing up the lockfile.

For supply chain security, install with hash verification: pip install -r requirements.txt --require-hashes. Generate hashes via pip-compile --generate-hashes requirements.in. This ensures every downloaded wheel matches a known SHA-256.

Dockerfile pattern for layer caching: `` COPY requirements.txt . RUN pip install -r requirements.txt --require-hashes COPY . . ` This caches the dependency layer until requirements.txt` changes, slashing rebuild times.

#!/bin/bash
# ── SCENARIO: You've built your weather app. Time to share it. ────────────────

# Make sure the virtual environment is active first:
source .venv/bin/activate

# Install the packages the app actually needs:
pip install requests==2.31.0
pip install python-dotenv==1.0.0

# ── STEP 1: Freeze the environment into a requirements file ───────────────────
# 'pip freeze' lists EVERY installed package with its exact version
# '>' redirects that output into a file called requirements.txt
pip freeze > requirements.txt

# Let's see what that file looks like:
cat requirements.txt

# ── STEP 2: Create a separate development requirements file ───────────────────
# Install development-only tools
pip install pytest black mypy pre-commit

# Freeze only the extras for dev (requires pip-tools or manual filtering)
pip freeze | grep -E "pytest|black|mypy|pre-commit" > requirements-dev.txt

# ── STEP 3: Simulate what a teammate would do on their machine ────────────────
# They clone your repo, then:
mkdir colleagues_machine_simulation
cd colleagues_machine_simulation
python -m venv .venv
source .venv/bin/activate

# One command installs EVERYTHING, at EXACTLY the same versions:
# '-r' means 'read from this file'
pip install -r ../requirements.txt

# ── STEP 4: Verify they got the same setup ────────────────────────────────────
pip list

# ── STEP 5: Check for differences ─────────────────────────────────────────────
pip freeze | diff -u ../requirements.txt -

A Real-World Mini Project Tying It All Together

Theory is fine, but let's build something real inside a virtual environment so the whole workflow clicks. We'll write a small script that fetches the current weather for a city using the requests library — a package we install inside a virtual environment, not globally.

This example shows the complete developer workflow you'll repeat on every Python project you ever build: create environment → activate → install dependencies → write code → freeze requirements → deactivate. Once this muscle memory kicks in, you'll do it automatically.

Pay attention to the Python script itself too. It runs perfectly inside the virtual environment because requests is installed there. If you deactivate the environment and try to run the same script with the global Python, it would fail with ModuleNotFoundError: No module named 'requests' — unless you also happen to have it globally. That's virtual environment isolation working exactly as intended.

The script uses a free weather API (Open-Meteo) that requires no API key — perfect for learning. It demonstrates error handling for network issues and API errors, showing real production considerations even in a demo.

# fetch_weather.py
# Run this INSIDE an active virtual environment where 'requests' is installed.
# Setup commands (run in terminal first):
#   python -m venv .venv
#   source .venv/bin/activate          (Mac/Linux)
#   pip install requests==2.31.0
#   pip freeze > requirements.txt
#   python fetch_weather.py

import requests  # Only available because we installed it in our virtual environment
import sys

# Open-Meteo is a free weather API — no API key needed, perfect for learning
WEATHER_API_BASE_URL = "https://api.open-meteo.com/v1/forecast"

# Coordinates for London, UK — change these to your city
LATITUDE = 51.5074
LONGITUDE = -0.1278
CITY_NAME = "London"

def fetch_current_temperature(latitude: float, longitude: float) -> dict:
    """
    Calls the Open-Meteo API and returns the current temperature data.
    Returns a dict with 'temperature' and 'unit' keys, or raises on failure.
    """
    # Build the query parameters the API expects
    query_params = {
        "latitude": latitude,
        "longitude": longitude,
        "current_weather": True,   # Ask for current conditions, not a forecast
        "temperature_unit": "celsius"
    }

    # requests.get() makes an HTTP GET request — this is why we installed 'requests'
    api_response = requests.get(WEATHER_API_BASE_URL, params=query_params, timeout=10)

    # Raise an exception immediately if the server returned an error status (4xx, 5xx)
    api_response.raise_for_status()

    # .json() parses the response body from a raw string into a Python dictionary
    weather_data = api_response.json()

    current_conditions = weather_data["current_weather"]
    return {
        "temperature": current_conditions["temperature"],
        "unit": "°C",
        "wind_speed_kmh": current_conditions["windspeed"]
    }


def display_weather_report(city: str, weather: dict) -> None:
    """Prints a clean, readable weather summary to the terminal."""
    print("\n" + "=" * 40)
    print(f"  Current Weather — {city}")
    print("=" * 40)
    print(f"  Temperature : {weather['temperature']}{weather['unit']}")
    print(f"  Wind Speed  : {weather['wind_speed_kmh']} km/h")
    print("=" * 40 + "\n")


def verify_environment():
    """Check if we're in a virtual environment before proceeding."""
    import sys
    if hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix):
        print(f"✓ Virtual environment active at: {sys.prefix}")
    else:
        print("⚠ WARNING: Not in a virtual environment!")
        print("  This script may still work if packages happen to be installed globally.")
        print("  But for reliable dependency management, activate your venv first.")
        response = input("  Continue anyway? (y/N): ")
        if response.lower() != 'y':
            sys.exit(1)


if __name__ == "__main__":
    verify_environment()
    print(f"\nFetching weather for {CITY_NAME}...")

    try:
        current_weather = fetch_current_temperature(LATITUDE, LONGITUDE)
        display_weather_report(CITY_NAME, current_weather)
    except requests.exceptions.ConnectionError:
        print("ERROR: No internet connection. Check your network and try again.")
        sys.exit(1)
    except requests.exceptions.HTTPError as http_err:
        print(f"ERROR: The weather API returned an error: {http_err}")
        sys.exit(1)
    except Exception as e:
        print(f"ERROR: Unexpected error: {e}")
        sys.exit(1)

Lock Your Environment With a Spec File, Not a Prayer

Pip freeze > requirements.txt is the bare minimum. But raw freeze is brittle. It dumps every dependency, including ones you don’t explicitly import. Your CI pipeline picks up different OS-level patches? Your environment breaks silently.

Use pip-compile from pip-tools instead. It creates a locked requirements.txt from a declarative requirements.in. That way you pin exact versions only for packages you actually need. Transitive dependencies get locked too, but you control the source.

This is what separates hobby projects from production pipelines. Locking transitive deps prevents a pandas-hotfix version from introducing an incompatible numpy build. Your teammates and your container build get exactly the same environment, down to the patch level.

Run pip-compile requirements.in once. Commit the generated requirements.txt. Never touch it manually.

# requirements.in
pandas
requests
flask

Activate Once, Forget Forever: Shell Integration Saves Hours

Activating a virtual environment manually every time you open a terminal is friction. And friction kills workflow.

Ship it with direnv (or autoenv if you're legacy). Drop a .envrc file in your project root that reads:

layout python3

That’s it. Every time you cd into that directory, direnv automatically activates the venv. Leave the directory? It deactivates. No source ./venv/bin/activate. No muscle memory required.

Direnv works with pyenv too. You can set a specific Python version per directory:

use python 3.12

The shell prompt changes to show the active env. One less mental context switch. Onboarding a junior dev? They cd into the repo, and everything just works. No docs needed for setup.

Stop wasting terminal history on activation commands. Automate it.

# .envrc
layout python3
# Optional: pin Python version
# use python 3.12

venv vs virtualenv vs pipenv vs Poetry — Pick the Right Tool

## 1. venv (stdlib)

Zero dependencies. Ships with Python 3.3+. Use for simple scripts, CI pipelines, or when you need zero overhead.

``bash python -m venv .venv source .venv/bin/activate pip install requests ``

Weakness: No lock file, no dependency resolution beyond pip's flat list. You'll get different versions on different machines unless you manually pin everything. No build system. No publish.

When to use: One-off scripts, throwaway containers, CI where you control the environment exactly.

## 2. virtualenv

The old guard. Needed for Python 2 legacy. Has extra flags like --copies (copy instead of symlink) and --symlinks (force symlinks). Still maintained but not needed for Python 3+.

``bash pip install virtualenv virtualenv --python=python2.7 .venv source .venv/bin/activate ``

When to use: You're maintaining a Python 2 codebase in 2026. Otherwise, use venv.

## 3. pipenv

Pipfile + Pipfile.lock. Auto-manages .venv in your project directory. Was supposed to be the future, but the resolver is slow, the project had long abandonment periods, and trust is broken.

``bash pip install pipenv pipenv install requests pipenv shell ``

Current status (2026): Still maintained but not recommended for new projects. The lock file works, but the resolver can take minutes for complex graphs. Use only if you're already on it and migration cost is too high.

When to use: You're already on it and can't migrate. Otherwise, skip.

## 4. Poetry

The 2026 standard. Uses pyproject.toml, generates poetry.lock, handles build system, and can publish to PyPI. Fast resolver, deterministic builds, and first-class support for both libraries and applications.

```bash # Install curl -sSL https://install.python-poetry.org | python3 -

# New project poetry new my-project cd my-project

# Add dependency poetry add requests

# Install from lock poetry install

# Switch Python version poetry env use /usr/bin/python3.11

# Build and publish poetry build poetry publish ```

When to use: Any team project, library, or application that needs reproducibility and deployment.

## 5. Feature Comparison

## 6. Decision Rule

• Simple script → venv
• Team application → Poetry
• Maintaining legacy → virtualenv
• Nowhere → pipenv (unless already on it, then stay until you can migrate)

pyenv + venv: Managing Multiple Python Versions Like a Pro

The Core Problem

Ubuntu 22.04 ships Python 3.10. Period. You need 3.12 for that shiny new library. System Python is frozen by apt. Don't touch it — break your OS. Enter pyenv.

pyenv Installation

``bash curl https://pyenv.run | bash ``

Add to ~/.bashrc: ``bash export PYENV_ROOT="$HOME/.pyenv" [[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)" ``

How Shims Work

pyenv inserts $PYENV_ROOT/shims at the front of your PATH. When you type python, the shim intercepts the call, reads .python-version (or falls back to global), and routes to the correct Python binary. No aliases, no symlink chaos.

Essential Commands

```bash # Install a specific version pyenv install 3.12.3

# Set for current directory (creates .python-version) pyenv local 3.12.3

# Set global default pyenv global 3.11.9

# Verify python --version # should show 3.12.3 ```

.python-version is a plain text file containing just the version string. Commit it.

Combining pyenv with venv

``bash cd /your/project pyenv local 3.12.3 python -m venv .venv source .venv/bin/activate ``

This creates a venv using the pyenv-managed Python 3.12.3. The venv is tied to that exact interpreter. No more "but I installed 3.12" confusion.

Team Pattern

Commit .python-version to git. Add .venv/ to .gitignore. Every dev runs: ``bash pyenv install python -m venv .venv source .venv/bin/activate ``

Reproducible. Fast. No fights.

Docker Consideration

Inside Docker, skip pyenv. Use official images: ``dockerfile FROM python:3.12-slim ``

pyenv is a host-side tool. Containers are disposable — just pick the right base image. Don't install pyenv in production images.