Virtual environments keep your Python projects isolated. Here's how to use them properly.

Why Virtual Environments?

Without them:

  • Project A needs requests==2.25
  • Project B needs requests==2.28
  • They conflict on your system

With virtual environments, each project has its own isolated packages.

Creating a Virtual Environment

# Create
python -m venv venv
 
# Activate (macOS/Linux)
source venv/bin/activate
 
# Activate (Windows)
venv\Scripts\activate
 
# Deactivate
deactivate

You'll see (venv) in your prompt when active.

Project Setup

Standard workflow:

# 1. Create project directory
mkdir myproject && cd myproject
 
# 2. Create virtual environment
python -m venv venv
 
# 3. Activate it
source venv/bin/activate
 
# 4. Install packages
pip install requests flask
 
# 5. Save dependencies
pip freeze > requirements.txt

requirements.txt

Lock your dependencies:

# requirements.txt
requests==2.28.1
flask==2.2.2
gunicorn==20.1.0

Install from file:

pip install -r requirements.txt

Pinning Versions

# Exact version (recommended for apps)
requests==2.28.1

# Minimum version
requests>=2.28.0

# Compatible release (same as >=2.28.0, ==2.28.*)
requests~=2.28.0

# Range
requests>=2.25.0,<3.0.0

Development Dependencies

Separate production and development:

# requirements.txt (production)
flask==2.2.2
gunicorn==20.1.0

# requirements-dev.txt
-r requirements.txt
pytest==7.2.0
black==22.12.0
mypy==0.991

Install for development:

pip install -r requirements-dev.txt

.gitignore

Never commit your virtual environment:

# Virtual environments
venv/
.venv/
env/
.env/
 
# Python
__pycache__/
*.pyc
*.pyo
.Python
 
# pip
pip-log.txt

Where to Put venv

Convention: project root, named venv or .venv:

myproject/
├── venv/           # or .venv/
├── src/
├── tests/
├── requirements.txt
└── README.md

Use .venv to hide it in file browsers.

pip Commands

# Install package
pip install requests
 
# Install specific version
pip install requests==2.28.1
 
# Upgrade package
pip install --upgrade requests
 
# Uninstall
pip uninstall requests
 
# List installed
pip list
 
# Show package info
pip show requests
 
# Export dependencies
pip freeze > requirements.txt
 
# Install from file
pip install -r requirements.txt

Upgrading Packages

Check for outdated packages:

pip list --outdated

Upgrade specific package:

pip install --upgrade requests

Upgrade all (careful!):

pip freeze | cut -d'=' -f1 | xargs pip install --upgrade

Multiple Python Versions

Specify Python version when creating:

# Use Python 3.11 specifically
python3.11 -m venv venv
 
# Or use full path
/usr/local/bin/python3.11 -m venv venv

Alternatives

pyenv + pyenv-virtualenv

Manage Python versions and environments:

pyenv install 3.11.0
pyenv virtualenv 3.11.0 myproject
pyenv activate myproject

Poetry

Modern dependency management:

poetry new myproject
poetry add requests
poetry install
poetry shell

pipenv

Combines pip and virtualenv:

pipenv install requests
pipenv shell

VS Code Integration

Add to .vscode/settings.json:

{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
    "python.terminal.activateEnvironment": true
}

VS Code will auto-activate the environment.

Troubleshooting

"Command not found" after activating:

# Make sure you're using the right Python
which python  # Should show venv path

Packages not found:

# Verify environment is active
echo $VIRTUAL_ENV

Permission errors:

# Don't use sudo with venv
pip install package  # Not: sudo pip install

Best Practices

  1. Always use virtual environments — Never install globally
  2. Pin exact versions — For reproducible builds
  3. Keep requirements updated — Run pip freeze after changes
  4. Use .venv naming — Hidden, clear purpose
  5. Never commit venv — Add to .gitignore
  6. Document Python version — In README or pyproject.toml

Quick Reference

# Create
python -m venv venv
 
# Activate
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows
 
# Install
pip install package
pip install -r requirements.txt
 
# Save
pip freeze > requirements.txt
 
# Deactivate
deactivate

Virtual environments are foundational to Python development. Use them for every project.

React to this post: