Appendix K — Getting Started with venv

K.1 Introduction to venv

The venv module is Python’s built-in tool for creating virtual environments. Introduced in Python 3.3 and standardized in PEP 405, it has become the official recommended way to create isolated Python environments. As a module in the standard library, venv is immediately available with any Python installation, requiring no additional installation step.

Virtual environments created with venv provide isolated spaces where Python projects can have their own dependencies, regardless of what dependencies other projects may have. This solves the common problem of conflicting package requirements across different projects and prevents changes to one project from affecting others.

K.2 Why Use venv?

Virtual environments are essential in Python development for several reasons:

  1. Dependency Isolation: Each project can have its own dependencies, regardless of other projects’ requirements
  2. Consistent Environments: Ensures reproducible development and deployment environments
  3. Clean Testing: Test against specific package versions without affecting the system Python
  4. Conflict Prevention: Avoids “dependency hell” where different projects need different versions of the same package
  5. Project Organization: Clearly separates project dependencies from system or global packages

K.3 Getting Started with venv

K.3.1 Creating a Virtual Environment

To create a virtual environment using venv, open a terminal and run:

# Basic syntax
python -m venv /path/to/new/virtual/environment

# Common usage (create a .venv directory in your project)
python -m venv .venv

The command creates a directory containing: - A Python interpreter copy - The pip package manager - A basic set of installed libraries - Scripts to activate the environment

K.3.2 Activating the Environment

Before using the virtual environment, you need to activate it. The activation process adjusts your shell’s PATH to prioritize the virtual environment’s Python interpreter and tools.

K.3.2.1 On Windows:

# Command Prompt
.venv\Scripts\activate.bat

# PowerShell
.venv\Scripts\Activate.ps1

K.3.2.2 On macOS and Linux:

source .venv/bin/activate

After activation, your shell prompt typically changes to indicate the active environment:

(.venv) user@computer:~/project$

All Python and pip commands now use the virtual environment’s versions instead of the system ones.

K.3.3 Deactivating the Environment

When you’re done working on the project, deactivate the environment:

deactivate

This restores your shell to its original state, using the system Python interpreter.

K.4 Advanced venv Options

K.4.1 Creating Environments with Specific Python Versions

To create an environment with a specific Python version, use that version’s interpreter:

# Using Python 3.8
python3.8 -m venv .venv

# On Windows with py launcher
py -3.8 -m venv .venv

K.4.2 Creating Environments Without pip

By default, venv installs pip in new environments. To create one without pip:

python -m venv --without-pip .venv

K.4.3 Creating System Site-packages Access

Normally, virtual environments are isolated from system site-packages. To allow access:

python -m venv --system-site-packages .venv

This creates an environment that can see system packages, but newly installed packages still go into the virtual environment.

K.4.4 Upgrading pip in a New Environment

Virtual environments often include an older pip version. It’s good practice to upgrade:

# After activating the environment
pip install --upgrade pip

K.5 Managing Dependencies with venv

While venv creates the environment, you’ll use pip to manage packages within it.

K.5.1 Installing Packages

With your environment activated:

# Install individual packages
pip install requests

# Install with version constraints
pip install "django>=4.0,<5.0"

K.5.2 Tracking Dependencies

To track installed packages:

# Generate a requirements file
pip freeze > requirements.txt

This creates a text file listing all installed packages and their versions.

K.5.3 Installing from Requirements

To recreate an environment elsewhere:

# Create and activate a new environment
python -m venv .venv
source .venv/bin/activate  # or Windows equivalent

# Install dependencies
pip install -r requirements.txt

K.6 Best Practices with venv

K.6.1 Directory Naming Conventions

Common virtual environment directory names include:

  • .venv: Hidden directory (less visible clutter)
  • venv: Explicit directory name
  • env: Shorter alternative

The .venv name is increasingly popular as it: - Keeps it hidden in file browsers - Makes it easy to add to .gitignore - Is recognized by many IDEs and tools

K.6.2 Version Control Integration

Never commit virtual environment directories to version control. Add them to .gitignore:

# .gitignore
.venv/
venv/
env/

K.6.3 Environment Management Across Projects

Create a new virtual environment for each project:

# Project A
cd project_a
python -m venv .venv

# Project B
cd ../project_b
python -m venv .venv

K.6.4 IDE Integration

Most Python IDEs integrate well with venv environments:

K.6.4.1 VS Code

  1. Open your project folder
  2. Press Ctrl+Shift+P
  3. Select “Python: Select Interpreter”
  4. Choose the environment from the list

K.6.4.2 PyCharm

  1. Go to Settings → Project → Python Interpreter
  2. Click the gear icon → Add
  3. Select “Existing Environment” and navigate to the environment’s Python

K.7 Comparing venv with Other Tools

K.7.1 venv vs. virtualenv

virtualenv is a third-party package that inspired the creation of venv.

  • venv: Built into Python, no installation needed, slightly fewer features
  • virtualenv: Third-party package, more features, better backwards compatibility

For most modern Python projects, venv is sufficient, but virtualenv offers some advanced options and supports older Python versions.

K.7.2 venv vs. conda

While both create isolated environments, they serve different purposes:

  • venv: Python-specific, lightweight, manages only Python packages
  • conda: Cross-language package manager, handles non-Python dependencies, preferred for scientific computing

K.7.3 venv vs. Poetry/PDM

These are newer tools that combine dependency management with virtual environments:

  • venv+pip: Separate tools for environments and package management
  • Poetry/PDM: All-in-one solutions with lock files, dependency resolution, packaging

K.8 Troubleshooting Common Issues

K.8.1 Activation Script Not Found

If you can’t find the activation script:

# List environment directory contents
ls -la .venv/bin  # macOS/Linux
dir .venv\Scripts  # Windows

Make sure the environment was created successfully and you’re using the correct path.

K.8.2 Packages Not Found After Installation

If packages are installed but not importable:

  1. Verify the environment is activated (check prompt prefix)
  2. Check if you have multiple Python installations
  3. Reinstall the package in the active environment

K.8.3 Permission Issues

If you encounter permission errors:

# On macOS/Linux
python -m venv --prompt myproject .venv

# On Windows, try running as administrator or using user directory

K.9 Script Examples for venv Workflows

K.9.1 Project Setup Script

#!/bin/bash
# setup_project.sh

# Create project directory
mkdir -p my_project
cd my_project

# Create basic structure
mkdir -p src/my_package tests docs

# Create virtual environment
python -m venv .venv

# Activate environment (adjust for your shell)
source .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install initial dev packages
pip install pytest black

# Create initial requirements
pip freeze > requirements.txt

echo "Project setup complete! Activate with: source .venv/bin/activate"

K.9.2 Environment Recreation Script

#!/bin/bash
# recreate_env.sh

# Remove old environment if it exists
rm -rf .venv

# Create fresh environment
python -m venv .venv

# Activate
source .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

echo "Environment recreated successfully!"

K.10 Conclusion

The venv module provides a simple, reliable way to create isolated Python environments directly from the standard library. While newer tools offer more features and automation, venv remains a fundamental building block of Python development workflows, offering an excellent balance of simplicity and utility.

For most Python projects, the combination of venv and pip provides a solid foundation for environment management. As projects grow in complexity, you can build upon this foundation with additional tools while maintaining the same core principles of isolation and reproducibility.