Skip to main content
Editor

Python Virtual Environments and pip: A Practical Guide

Intermediate20 min4 exercises60 XP
0/4 exercises

Imagine you're a carpenter working on two different projects. One needs tiny finishing nails and the other needs heavy-duty bolts. You wouldn't dump all your hardware into one toolbox - you'd have separate toolboxes so the right parts are always ready for the right job.

Python virtual environments work the same way. Each project gets its own isolated toolbox of packages and dependencies. This means Project A can use version 1.0 of a library while Project B uses version 2.0, and they'll never interfere with each other.

In this tutorial, you'll learn why virtual environments matter, how to create and use them, and how to manage packages with pip and requirements.txt.

Why Do You Need Virtual Environments?

Without virtual environments, every package you install goes into one global Python installation. This seems fine at first, but it quickly becomes a problem.

Imagine you built a website last year using requests version 2.25. Now you're starting a new project that needs requests version 2.31. If you upgrade globally, your old website might break. If you don't upgrade, your new project can't use the latest features.

The dependency conflict problem
# The "dependency conflict" problem:
# Project A needs:
project_a_deps = {
'requests': '2.25.0',
'flask': '1.1.4',
}
# Project B needs:
project_b_deps = {
'requests': '2.31.0',
'flask': '3.0.0',
}
# Without virtual environments, you can only have ONE version!
for pkg in project_a_deps:
v_a = project_a_deps[pkg]
v_b = project_b_deps[pkg]
if v_a != v_b:
print(f'CONFLICT: {pkg} needs {v_a} (A) vs {v_b} (B)')
print('\nSolution: Give each project its own environment!')
Output
CONFLICT: requests needs 2.25.0 (A) vs 2.31.0 (B)
CONFLICT: flask needs 1.1.4 (A) vs 3.0.0 (B)

Solution: Give each project its own environment!

How Do You Create and Activate a Virtual Environment?

Python 3 ships with a built-in module called venv that creates virtual environments. No extra installation needed - it's ready to go.

Here's the workflow: you create the environment once, then activate it every time you work on that project. When activated, any packages you install go only into that environment.

Creating and activating a virtual environment
# Terminal commands to create and activate a venv:
# (These run in your system terminal, not in the browser)
steps = [
('1. Create the environment', 'python -m venv myenv'),
('2a. Activate (macOS/Linux)', 'source myenv/bin/activate'),
('2b. Activate (Windows)', 'myenv\\Scripts\\activate'),
('3. Your prompt changes to', '(myenv) $'),
('4. Deactivate when done', 'deactivate'),
]
for step, command in steps:
print(f'{step}:')
print(f' $ {command}\n')
Output
1. Create the environment:
  $ python -m venv myenv

2a. Activate (macOS/Linux):
  $ source myenv/bin/activate

2b. Activate (Windows):
  $ myenv\Scripts\activate

3. Your prompt changes to:
  $ (myenv) $

4. Deactivate when done:
  $ deactivate

When the environment is active, you'll see its name in parentheses at the start of your terminal prompt. This is your visual confirmation that you're working inside the isolated environment.

What is inside a venv folder?
# What's inside a virtual environment folder?
import os
venv_contents = {
'bin/ (or Scripts/ on Windows)': 'Python executable + activate script',
'lib/pythonX.Y/site-packages/': 'Installed packages go here',
'include/': 'C header files for compiling extensions',
'pyvenv.cfg': 'Configuration file pointing to base Python',
}
print('Inside a virtual environment folder:\n')
for folder, purpose in venv_contents.items():
print(f' {folder}')
print(f' -> {purpose}\n')
Output
Inside a virtual environment folder:

  bin/ (or Scripts/ on Windows)
    -> Python executable + activate script

  lib/pythonX.Y/site-packages/
    -> Installed packages go here

  include/
    -> C header files for compiling extensions

  pyvenv.cfg
    -> Configuration file pointing to base Python

How Do You Install Packages with pip?

pip is Python's package installer. It downloads packages from PyPI (the Python Package Index) - a massive online catalog with over 500,000 packages. Think of PyPI as an app store for Python.

Once your virtual environment is active, every pip install command puts packages only into that environment. Here are the essential commands:

Essential pip commands
# Essential pip commands:
pip_commands = [
('pip install requests', 'Install latest version'),
('pip install requests==2.31.0', 'Install exact version'),
('pip install requests>=2.25', 'Install 2.25 or newer'),
('pip install --upgrade requests', 'Upgrade to latest'),
('pip uninstall requests', 'Remove a package'),
('pip list', 'Show all installed packages'),
('pip show requests', 'Details about one package'),
]
for cmd, desc in pip_commands:
print(f'$ {cmd}')
print(f' {desc}\n')
Output
$ pip install requests
  Install latest version

$ pip install requests==2.31.0
  Install exact version

$ pip install requests>=2.25
  Install 2.25 or newer

$ pip install --upgrade requests
  Upgrade to latest

$ pip uninstall requests
  Remove a package

$ pip list
  Show all installed packages

$ pip show requests
  Details about one package
Understanding version specifiers
# Version specifiers explained:
specifiers = {
'==2.31.0': 'Exactly this version',
'>=2.25.0': 'This version or newer',
'<=3.0.0': 'This version or older',
'>=2.25,<3.0': 'At least 2.25 but below 3.0',
'~=2.31': 'Compatible release (>=2.31.0, <2.32.0)',
'!=2.30.0': 'Any version except this one',
}
print('pip version specifiers:\n')
for spec, meaning in specifiers.items():
print(f' requests{spec}')
print(f' -> {meaning}\n')
Output
pip version specifiers:

  requests==2.31.0
    -> Exactly this version

  requests>=2.25.0
    -> This version or newer

  requests<=3.0.0
    -> This version or older

  requests>=2.25,<3.0
    -> At least 2.25 but below 3.0

  requests~=2.31
    -> Compatible release (>=2.31.0, <2.32.0)

  requests!=2.30.0
    -> Any version except this one

What Is requirements.txt and Why Does It Matter?

Imagine handing your project to a teammate. They need to install every package your project depends on. Telling them "just install requests and flask and maybe pandas" is messy and error-prone.

A requirements.txt file is a simple text file that lists every package and its exact version. Your teammate just runs one command and everything gets installed automatically.

Simulating a requirements.txt file
# Creating and using requirements.txt:
# Step 1: Freeze current packages to a file
# $ pip freeze > requirements.txt
# Step 2: Install from the file on another machine
# $ pip install -r requirements.txt
# Let's simulate what requirements.txt looks like:
requirements = [
'certifi==2023.11.17',
'charset-normalizer==3.3.2',
'flask==3.0.0',
'idna==3.6',
'requests==2.31.0',
'urllib3==2.1.0',
]
print('# requirements.txt')
print('# Generated by: pip freeze > requirements.txt\n')
for req in requirements:
print(req)
print(f'\nTotal packages: {len(requirements)}')
Output
# requirements.txt
# Generated by: pip freeze > requirements.txt

certifi==2023.11.17
charset-normalizer==3.3.2
flask==3.0.0
idna==3.6
requests==2.31.0
urllib3==2.1.0

Total packages: 6

Notice that pip freeze also lists transitive dependencies - packages that your packages depend on. For example, flask needs werkzeug, so werkzeug shows up even though you didn't install it directly.


How Do You Manage Dependencies Across Environments?

Real projects often have different dependencies for different situations. Your development machine might need testing tools and linters, but your production server only needs the core packages.

Splitting requirements by environment
# Common pattern: multiple requirements files
files = {
'requirements.txt': [
'flask==3.0.0',
'requests==2.31.0',
'sqlalchemy==2.0.23',
],
'requirements-dev.txt': [
'-r requirements.txt', # includes base requirements
'pytest==7.4.3',
'black==23.12.0',
'mypy==1.7.1',
],
}
for filename, deps in files.items():
print(f'# {filename}')
for dep in deps:
print(f' {dep}')
print()
Output
# requirements.txt
  flask==3.0.0
  requests==2.31.0
  sqlalchemy==2.0.23

# requirements-dev.txt
  -r requirements.txt
  pytest==7.4.3
  black==23.12.0
  mypy==1.7.1

The -r requirements.txt line inside requirements-dev.txt means "include everything from the base file too." This way, developers get all the core packages plus development tools, while production only installs the essentials.

Complete new project workflow
# The complete workflow for a new project:
workflow = [
('1', 'mkdir my_project && cd my_project', 'Create project folder'),
('2', 'python -m venv .venv', 'Create virtual environment'),
('3', 'source .venv/bin/activate', 'Activate it'),
('4', 'pip install flask requests', 'Install packages'),
('5', 'pip freeze > requirements.txt', 'Save dependencies'),
('6', 'echo ".venv/" >> .gitignore', 'Exclude venv from git'),
('7', 'git add . && git commit', 'Commit your project'),
]
print('New project setup workflow:\n')
for num, cmd, desc in workflow:
print(f' Step {num}: {desc}')
print(f' $ {cmd}\n')
Output
New project setup workflow:

  Step 1: Create project folder
    $ mkdir my_project && cd my_project

  Step 2: Create virtual environment
    $ python -m venv .venv

  Step 3: Activate it
    $ source .venv/bin/activate

  Step 4: Install packages
    $ pip install flask requests

  Step 5: Save dependencies
    $ pip freeze > requirements.txt

  Step 6: Exclude venv from git
    $ echo ".venv/" >> .gitignore

  Step 7: Commit your project
    $ git add . && git commit

Practice Exercises

These exercises test your understanding of virtual environments, pip, and dependency management. Since we're in a browser, we'll simulate these concepts with Python code.

Parse a Requirements File
Write Code

Write a function called parse_requirements(text) that takes a string representing a requirements.txt file (one package per line in the format name==version). Return a dictionary mapping package names to their versions. Ignore empty lines and lines starting with #.

def parse_requirements(text):
# Parse the requirements text into a dictionary
pass
Fix the Dependency Resolver
Fix the Bug

The code below simulates a dependency resolver that checks if installed packages satisfy requirements. There are bugs causing incorrect output. Fix them so the resolver correctly identifies which requirements are met and which are not.

def check_dependencies(installed, required):
results = []
for pkg, req_version in sorted(required.items()):
if pkg in installed:
inst_version = installed[pkg]
if inst_version == req_version:
results.append(f'{pkg}: OK ({inst_version})')
else:
results.append(f'{pkg}: MISMATCH (need {req_version}, have {inst_version})')
else:
results.append(f'{pkg}: MISSING')
return results
installed = {
'flask': '3.0.0',
'requests': '2.25.0',
'numpy': '1.24.0',
}
required = {
'flask': '3.0.0',
'requests': '2.31.0',
'pandas': '2.1.4',
}
results = check_dependencies(installed, required)
for r in results:
print(r)
total = len(required)
ok_count = len([r for r in results if 'OK' in r])
print(f'\n{ok_count}/{total} dependencies satisfied')
Predict the Environment Check
Predict Output

Read the code carefully and predict the output. The code simulates checking which virtual environment is active and what packages are available.

environments = {
'global': ['pip', 'setuptools'],
'project_a': ['pip', 'setuptools', 'flask', 'requests'],
'project_b': ['pip', 'setuptools', 'django', 'celery'],
}
active_env = 'project_a'
def is_available(package):
return package in environments[active_env]
packages_to_check = ['flask', 'django', 'requests', 'pip']
for pkg in packages_to_check:
status = 'installed' if is_available(pkg) else 'not found'
print(f'{pkg}: {status}')
Build a Virtual Environment Manager
Write Code

Create a class called VenvManager that simulates managing virtual environments:

  • __init__(): Initialize with an empty dictionary envs and set active to None
  • create(name): Add an environment with name as key and an empty list as value. Print Created: name
  • activate(name): Set active to name if it exists. Print Activated: name. If it doesn't exist, print Error: name not found
  • install(package): Append package to the active environment's list. Print Installed: package. If no environment is active, print Error: no active environment
  • list_packages(): Print each package in the active environment, one per line. If no environment is active, print Error: no active environment. If the environment is empty, print No packages installed
  • class VenvManager:
    # Build your virtual environment manager
    pass

    Related Tutorials

    Was this tutorial helpful?