Chapter 43 of 54

pip & Virtual Environments

In the previous chapter, you learned how to use modules like math and random that come built into Python. But the real power of Python comes from the hundreds of thousands of third-party packages written by other developers: packages for web development, data science, machine learning, automation and much more.

To use those packages, you need two tools: pip, which downloads and installs packages, and virtual environments, which keep the packages of different projects separate from each other. Every professional Python developer uses both every day.

What is pip?

pip is Python's package installer. It downloads packages from PyPI (the Python Package Index, pypi.org) and installs them so you can import them in your code.

pip comes bundled with Python, so if you installed Python from python.org, you already have it. Check it from your terminal (Command Prompt, PowerShell or a macOS/Linux terminal):

python -m pip --version

You will see something like:

pip 26.2.1 from ...\site-packages\pip (python 3.14)

The exact version numbers on your machine may be different, and that is fine.

Tip: On macOS and Linux, the command is often python3 instead of python. Use whichever one runs Python on your system.

Why python -m pip instead of just pip?

You can type pip install ... directly, but if you have more than one Python version installed, pip might belong to a different Python than the one you run your code with. Writing python -m pip means "run the pip that belongs to this Python", so the package always lands in the right place. We will use this form throughout the chapter.


Installing a Package

Let's install humanize, a small package that turns numbers into human-friendly text:

python -m pip install humanize

pip downloads the package from PyPI and installs it. Now you can import it just like a built-in module:

import humanize

print(humanize.intcomma(1234567))
print(humanize.naturalsize(1500000))
print(humanize.ordinal(3))

Output:

1,234,567
1.5 MB
3rd

If you try to import a package that is not installed, Python raises an error:

ModuleNotFoundError: No module named 'humanize'

This error almost always means "you forgot to install it" or "you installed it into a different Python".


Common pip Commands

CommandWhat it does
python -m pip install humanizeInstalls the latest version
python -m pip install humanize==4.16.0Installs an exact version
python -m pip install "humanize>=4.0"Installs version 4.0 or newer
python -m pip install --upgrade humanizeUpgrades to the latest version
python -m pip uninstall humanizeRemoves the package
python -m pip listLists all installed packages
python -m pip show humanizeShows details (version, location, dependencies)
python -m pip freezePrints installed packages in name==version format

Notice the quotes around "humanize>=4.0". Without them, the terminal would treat > as "redirect output to a file".

Here is what pip list looks like in a fresh environment with only humanize installed:

Package  Version
-------- -------
humanize 4.16.0
pip      26.2.1

The Problem: Global Packages Clash

By default, pip installs packages into one shared, system-wide location. That works for a single small project, but quickly causes trouble:

Project A (old college project)  needs  django 4.2
Project B (new internship task)  needs  django 5.2

Global site-packages can hold only ONE version of django.
Installing 5.2 for Project B breaks Project A.

There are other problems too: your global Python fills up with packages you no longer remember installing, and you cannot easily tell a teammate exactly which packages your project needs.

The solution is a virtual environment.


What is a Virtual Environment?

A virtual environment is an isolated folder containing its own Python interpreter link and its own set of installed packages. Packages installed inside it do not affect any other project or your global Python.

my-projects/
├── project-a/
│   ├── .venv/        <- has django 4.2
│   └── app.py
└── project-b/
    ├── .venv/        <- has django 5.2
    └── app.py

Each project gets its own .venv folder, so the two Django versions never meet. Python includes the venv module for this, so nothing extra needs to be installed. (On Ubuntu/Debian Linux, the system Python ships it separately; if python3 -m venv fails, install it with sudo apt install python3-venv.)


Creating and Using a Virtual Environment

Step 1: Create it

Open a terminal inside your project folder and run:

python -m venv .venv

This creates a folder named .venv. The name is only a convention (some people use venv or env), but .venv is the most common choice and many editors detect it automatically.

Step 2: Activate it

The activation command depends on your operating system:

SystemCommand
Windows (Command Prompt).venv\Scripts\activate
Windows (PowerShell).venv\Scripts\Activate.ps1
macOS / Linuxsource .venv/bin/activate

Once activated, your prompt shows the environment name:

(.venv) C:\projects\project-b>

Now python and pip refer to the environment's copies, and anything you install goes into .venv only.

Note: If PowerShell says running scripts is disabled, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once, then try again.

Step 3: Install packages and work

python -m pip install humanize
python app.py

Step 4: Deactivate when done

deactivate

The (.venv) prefix disappears and you are back to the global Python.

Checking whether you are inside a virtual environment

Python can tell you itself. Inside a virtual environment, sys.prefix (the environment's folder) differs from sys.base_prefix (the original Python installation):

import sys

print(sys.prefix != sys.base_prefix)

Output (when run with the environment activated):

True

With no environment active, it prints False.


Sharing Your Project: requirements.txt

You should never share or commit the .venv folder itself. It is large and tied to your machine. Instead, you share a list of packages, and everyone recreates the environment.

Save your packages

python -m pip freeze > requirements.txt

This writes a file like:

humanize==4.16.0

Recreate the environment on another machine

python -m venv .venv

# Windows (Command Prompt)
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

python -m pip install -r requirements.txt

The -r flag tells pip to read package names from the file. Your teammate now has exactly the same versions as you.

Also add .venv/ to your .gitignore so Git ignores the folder:

.venv/

Common Mistakes

  • Forgetting to activate the environment. You install a package, run your script and still get ModuleNotFoundError. Check that your prompt shows (.venv), and that your editor (for example VS Code) is using the .venv interpreter.

  • Using bare pip with multiple Pythons installed. The package goes to a different Python. Prefer python -m pip.

  • Committing .venv to Git. Commit requirements.txt instead.

  • Moving or renaming the .venv folder. Virtual environments contain hard-coded paths and usually break when moved. Just delete it and create a new one.

  • The "externally-managed-environment" error on Linux/macOS. Many Linux distributions (and Homebrew Python) block pip install into the system Python to protect the operating system. This is not a bug; it is telling you to use a virtual environment. Create one and install there.

  • Using sudo pip install. This can break system tools. A virtual environment never needs sudo.


Other Tools You May Hear About

pip and venv are the standard tools built into Python, and they are all you need to start. As you work on bigger projects you may come across alternatives that combine both jobs:

  • uv - a very fast package and project manager that has become popular recently.

  • Poetry - manages dependencies and packaging using a pyproject.toml file.

  • conda - popular in data science; it can also install non-Python libraries.

They all solve the same problem you learned here: installing packages into an isolated environment per project.


Summary

TaskCommand
Create an environmentpython -m venv .venv
Activate (Windows).venv\Scripts\activate
Activate (macOS/Linux)source .venv/bin/activate
Install a packagepython -m pip install name
Save dependenciespython -m pip freeze > requirements.txt
Install from filepython -m pip install -r requirements.txt
Leave the environmentdeactivate

Golden rule: one project, one virtual environment. Create it first, activate it, then install packages.

With pip and virtual environments in your toolkit, you can safely use any package from PyPI in your projects. Next, we will learn how to handle errors gracefully with exception handling.