Python Virtual Environments Guide
A beginner-friendly guide to Python virtual environments and package management.
This document explains: - venv - activation - pip - requirements.txt - Poetry - PEP 668 - common problems in 42 School environments
Virtual environments are essential for modern Python development.
What is a Virtual Environment?
A virtual environment is an isolated Python environment.
It allows each project to: - have its own packages - use different library versions - avoid conflicts with system Python
Without virtual environments: - projects may break each other - package versions may conflict - system Python can become unstable
Why Use Virtual Environments?
Virtual environments help: - isolate dependencies - create reproducible projects - avoid permission issues - protect system Python - simplify collaboration
Creating a Virtual Environment
Python includes venv by default.
Create venv
python3 -m venv venv
This creates a folder called:
venv/
Containing: - Python executable - pip - installed packages - activation scripts
Common Naming
Most projects use:
venv/
Other common names:
- .venv
- env
Activating the Virtual Environment
The environment must be activated before installing packages.
Linux / macOS
source venv/bin/activate
Windows CMD
venv\Scripts\activate.bat
Windows PowerShell
venv\Scripts\Activate.ps1
Successful Activation
The terminal usually changes.
Example:
(venv) user@computer:~/project$
This means the environment is active.
Checking the Python Path
Use:
which python3
Example output:
/home/user/project/venv/bin/python3
If it shows:
/usr/bin/python3
then the venv is probably NOT activated.
Deactivating the Environment
deactivate
This returns to the system Python.
pip
pip is Python's package manager.
Used for: - installing packages - updating packages - removing packages
Installing Packages
pip install pydantic
Installing Specific Versions
pip install "pydantic>=2"
Installing Multiple Packages
pip install flake8 mypy requests
Viewing Installed Packages
pip list
requirements.txt
requirements.txt stores project dependencies.
Useful for: - reproducibility - collaboration - deployment
Creating requirements.txt
pip freeze > requirements.txt
Example requirements.txt
pydantic==2.11.0
mypy==1.15.0
flake8==7.2.0
Installing from requirements.txt
pip install -r requirements.txt
Why requirements.txt Matters
Without it: - other users may install wrong versions - projects may stop working - environments become inconsistent
Poetry
Poetry is a more advanced Python dependency manager.
It replaces: - pip - requirements.txt - manual dependency handling
Poetry Features
Poetry: - manages dependencies - creates virtual environments - handles package versions - simplifies project management
Installing Poetry
Linux/macOS:
curl -sSL https://install.python-poetry.org | python3 -
Creating a Poetry Project
poetry init
Installing Dependencies
poetry add pydantic
Activating Poetry Environment
poetry shell
Installing from pyproject.toml
poetry install
pyproject.toml
Poetry stores dependencies in:
pyproject.toml
Instead of: - requirements.txt
Example pyproject.toml
[tool.poetry.dependencies]
python = "^3.10"
pydantic = "^2.11"
PEP 668
PEP 668 protects system Python environments.
Modern Linux distributions may block:
pip install package
outside virtual environments.
Common Error
externally-managed-environment
This is extremely common on: - Ubuntu - Debian - 42 machines
Why This Happens
The operating system wants to protect: - system Python - system packages - package manager integrity
Recommended Solution
Use virtual environments:
python3 -m venv venv
source venv/bin/activate
Then install packages normally.
Alternative Solution
Sometimes users install locally:
pip install --user package
But virtual environments are cleaner.
Common Problems in 42 School
42 environments often have: - limited permissions - restricted system access - outdated packages - disk quota issues
Common Problem: No Permission
Example:
Permission denied
Usually solved by: - using venv - avoiding sudo
Common Problem: PEP 668
Example:
externally-managed-environment
Solution: - create a venv
Common Problem: No Space Left on Device
Example:
OSError: [Errno 28] No space left on device
Very common in:
- /tmp
- home directories
- cached pip files
Possible Solutions
Clean pip cache:
pip cache purge
Remove unused venvs:
rm -rf venv
Common Problem: Wrong Python Version
Check version:
python3 --version
Common Problem: Missing Packages
Example:
ModuleNotFoundError: No module named 'pydantic'
Usually means: - venv not activated - package not installed
Common Problem: which python3
If this returns:
/usr/bin/python3
the venv is probably inactive.
Common Problem: Broken venv
Sometimes virtual environments break.
Fix:
rm -rf venv
python3 -m venv venv
Good Project Workflow
Step 1
Create project folder:
mkdir my_project
cd my_project
Step 2
Create virtual environment:
python3 -m venv venv
Step 3
Activate environment:
source venv/bin/activate
Step 4
Install dependencies:
pip install pydantic mypy flake8
Step 5
Save dependencies:
pip freeze > requirements.txt
Recommended .gitignore
Do NOT upload virtual environments to GitHub.
Example:
venv/
__pycache__/
*.pyc
Best Practices
- Always use virtual environments
- Never commit venv folders
- Keep requirements.txt updated
- Prefer precise package versions
- Activate venv before working
- Avoid using sudo pip install
Summary Table
| Tool / Concept | Purpose |
|---|---|
| venv | Isolated Python environment |
| pip | Package manager |
| requirements.txt | Stores dependencies |
| Poetry | Advanced dependency manager |
| PEP 668 | Protects system Python |
| activate | Enables virtual environment |
Final Notes
Virtual environments are one of the most important parts of modern Python development.
Understanding them helps avoid: - dependency conflicts - broken projects - permission issues - package problems
This becomes especially important in: - 42 projects - team environments - APIs - large Python applications - deployment systems