Virtual Environments

Virtual environments are the foundation of every reliable Python project. The handbook explains what a venv is, why you need one, and how to manage Python interpreters and isolated environments with modern tools.

Concepts

Tools

Migration paths

More Virtual Environments pages

Everything else tagged virtual-environments, grouped by section. Pages featured above are not repeated here.

How To

• How to create and use a Python virtual environment with venv
• How to customize uv's virtual environment location
• How to fix the "externally-managed-environment" error
• How to require a virtualenv when installing packages with pip?
• How to use pip in a uv virtual environment

Explanation

• Do I need a project to use uv?
• Should I use Homebrew to install Python?
• What is a .python-version file?
• What is PEP 668?

Reference

• pyenv-virtualenv

From the blog

Posts tagged virtual-environments.

• Jul 19, 2025

  uv 0.8 Release: Automatic Python Installation to PATH

  uv 0.8 adds automatic Python executable installation to PATH, making uv-managed Python versions available system-wide.

• Jun 25, 2025

  Managing Python Versions In Your uv Projects

  How .python-version files, requires-python, and uv work together to manage Python versions in your projects.

• Feb 19, 2025

  Why Use uv Projects Instead of requirements.txt?

  Comparing requirements.txt and pyproject.toml approaches to Python dependency management, and why uv projects offer more.

• Feb 12, 2025

  Flexible Python Version Management with uv and tox

  Solve tox Python version mismatch errors by using uvx to run tox with any Python version on demand.

• Mar 4, 2024

  Require pip to install packages in virtual environment

  Configure pip to only install packages inside virtual environments using the global.require-virtualenv setting.

• Feb 5, 2024

  Quick start guide for Python development on a Mac

  A quick start guide for setting up Python on macOS using pyenv and Poetry, with a note on the modern uv alternative.