Lesson 4: Python Virtual Environments & Package Management
Managing dependencies is a critical skill for any Python developer. You need a way to isolate the packages required for one project from the packages required for another. This is where virtual environments come in.
This lesson explains why virtual environments are essential and introduces the modern tools you'll be using in 2025 to manage them and the packages they contain.
1. Why Do You Need Virtual Environments?
Imagine you have two projects:
- Project A requires
pydanticversion 1.10.
- Project B is a new project that requires
pydanticversion 2.7.
If you install packages globally (i.e., into your main system Python), you can only have one version of pydantic installed at a time. Installing version 2.7 for Project B would break Project A.
A virtual environment is a self-contained directory that contains a specific version of Python plus all the packages required for a specific project. It's a complete, isolated workspace.
2. uv: The All-in-One Tool for 2025
In the past, you might have used venv to create environments and pip to install packages into them. In 2025, the landscape has changed. uv, the ultra-fast tool from Astral (the makers of ruff), does both jobs better and faster.
Creating and Activating a Virtual Environment with uv
1. Navigate to your project folder:
mkdir my-ai-project
cd my-ai-project
2. Create the virtual environment:
uv will create a .venv folder in your project directory.
``bash
uv venv
`
3. Activate the environment:
Activation modifies your shell's PATH to point to the Python interpreter and scripts inside .venv. Your shell prompt will usually change to show that you're "in" the environment.
- macOS / Linux:
`bash
source .venv/bin/activate
`
- Windows (PowerShell):
`bash
.venv\Scripts\Activate.ps1
`
4. Deactivate the environment:
When you're done working on the project, you can deactivate the environment to return to your global Python context.
`bash
deactivate
`
to your project's .gitignore file. You should never commit your virtual environment to version control.
3. Managing Dependencies with
uv pip
Once your virtual environment is activated, you can install packages.
uv pip is a drop-in, much faster replacement for the standard pip.
Installing Packages
bash
Activate your environment first!
source .venv/bin/activateInstall a specific package
uv pip install pydanticInstall a specific version
uv pip install "pydantic==2.7.1"Install from a requirements file
uv pip install -r requirements.txtFreezing Dependencies: requirements.txt
A requirements.txt file is a simple text file that lists all the packages and their exact versions required for your project. This allows other developers (or your production server) to replicate your environment perfectly.
file:
Use uv pip freeze to output all the packages currently installed in your environment.
uv pip freeze > requirements.txt
Your
requirements.txt file will look something like this:
# requirements.txt
pydantic==2.7.1
pydantic-core==2.18.2
python-dotenv==1.0.1
requests==2.31.0
...
Best Practice: Always include a requirements.txt file in your project's root directory and keep it updated as you add or remove dependencies.
4. The Modern Development Workflow
Here is the complete, modern workflow for starting a new AI project:
1. Create the project directory.
`bash
mkdir my-new-agent && cd my-new-agent
`
2. Create the virtual environment.
`bash
uv venv
`
3. Activate it.
`bash
source .venv/bin/activate
`
4. Install your base packages.
`bash
uv pip install ruff pydantic requests python-dotenv
`
5. Start coding!
Create your main.py, .env, etc.
6. Update requirements.txt before committing.
`bash
uv pip freeze > requirements.txt
git add .
git commit -m "Initial project setup"
``
This workflow ensures your projects are isolated, reproducible, and easy for others to contribute to.