Skip to content
Kuza Ndoto Academy

pip & Virtual Environments

Beginner → IntermediateChapter 6 · Page 33 of 565 min readUpdated 15 Nov 2026

pip is Python's package installer: it downloads libraries other people have written, such as requests or django. A virtual environment is a private folder of packages for one project, so different projects never fight over versions.

What is pip?

The Python Package Index (PyPI, at pypi.org) hosts hundreds of thousands of free packages. pip is the tool that installs them. It comes with Python, and the safest way to run it is through the interpreter with python -m pip, which guarantees you use the pip that belongs to the Python you're running.

python -m pip --version
pip 24.3.1 from C:\Users\Amina\AppData\Local\Programs\Python\Python313\Lib\site-packages\pip (python 3.13)

Your version numbers and path will differ. On macOS and Linux, use python3 wherever this page says python; on Windows you can also use the launcher py.

Why you need virtual environments

Imagine you built a school project last year with Django 4.2 and today you're starting a new site with Django 5.1. If both projects shared one global set of packages, upgrading for the new project could break the old one. A virtual environment ("venv") solves this: each project gets its own folder containing its own Python and its own packages.

  • Projects stay independent: different versions can live side by side.
  • You can delete and rebuild an environment without touching anything else.
  • You can record exactly what a project needs, so classmates or a server can reproduce it.
No venvs: one global Python school-site new-site site-packages Django 4.2 or 5.1? only one version can be installed With venvs: one environment per project school-site/ .venv Python 3.13 Django 4.2 requests new-site/ .venv Python 3.13 Django 5.1 pandas
Figure 1. Without virtual environments, every project shares one set of packages and versions can clash. With a .venv in each project folder, each project keeps exactly the versions it needs.

Creating and activating a virtual environment

Open a terminal in your project folder and run the built-in venv module. The last word is the folder name; .venv is the common convention.

mkdir weather-app
cd weather-app
python -m venv .venv

Creating the folder isn't enough: you must activate it in every new terminal window. The command depends on your system:

System and shellActivate command
Windows PowerShell.venv\Scripts\Activate.ps1
Windows Command Prompt (cmd).venv\Scripts\activate.bat
macOS or Linux (bash, zsh)source .venv/bin/activate

When it works, your prompt starts with (.venv). From now on, python and pip in that terminal refer to the environment's copies.

(.venv) PS C:\Users\Amina\weather-app> python -c "import sys; print(sys.prefix)"
C:\Users\Amina\weather-app\.venv

When you're finished, type deactivate to return to the normal system Python.

Common mistake

In PowerShell you might see "running scripts is disabled on this system" when activating. PowerShell blocks scripts by default. Many developers allow locally created scripts for their own user account by running Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser once. If you'd rather not change that setting, use Command Prompt and .venv\Scripts\activate.bat instead.

Installing and managing packages

With the environment active, install packages by name. pip also installs anything the package depends on.

python -m pip install requests              # latest version
python -m pip install "requests==2.32.3"    # an exact version
python -m pip install --upgrade requests    # upgrade to the newest
python -m pip list                          # everything installed here
python -m pip show requests                 # details about one package
python -m pip uninstall requests            # remove a package

Version specifiers let you say which versions are acceptable:

SpecifierMeaning
django==5.1.4Exactly this version
django>=5.05.0 or newer
django>=5.0,<6.0Any 5.x version
django~=5.1.0Compatible release: 5.1.0 or newer, but below 5.2

Put specifiers containing < or > inside quotes on the command line, otherwise the shell treats those symbols as redirection.

requirements.txt: sharing your setup

pip freeze prints every installed package with its exact version. Saving that list in a file called requirements.txt is the standard way to record what a project needs.

python -m pip freeze > requirements.txt

After installing requests, the file looks something like this (your versions may differ):

certifi==2024.8.30
charset-normalizer==3.4.0
idna==3.10
requests==2.32.3
urllib3==2.2.3

Notice that requests brought four helper packages with it. Anyone who downloads your project can recreate the same environment in two commands:

python -m venv .venv
python -m pip install -r requirements.txt   # run this after activating .venv

A typical project workflow

  1. Create a project folder and cd into it.
  2. Run python -m venv .venv.
  3. Activate the environment (check for (.venv) in the prompt).
  4. Install packages with python -m pip install ....
  5. Save them with python -m pip freeze > requirements.txt.
  6. If you use Git, add .venv/ to your .gitignore file and commit requirements.txt instead.

In VS Code, open the project folder and choose "Python: Select Interpreter" from the Command Palette, then pick the interpreter inside .venv. The editor and its terminal will then use your environment automatically.

Common mistake

Installing packages before activating the environment puts them in your global Python, and then your project can't "see" them (or worse, it seems to work on your laptop but nowhere else). Always check for (.venv) before running pip install.

Warning

Don't copy, rename or move a .venv folder, and don't commit it to Git: it contains paths specific to your computer. If something goes wrong, delete the folder and recreate it from requirements.txt. On some Linux systems, installing into the system Python gives an "externally-managed-environment" error; that's a sign to use a virtual environment.

Tip

If your terminal says pip is "not recognised", use python -m pip (or py -m pip on Windows). It works even when the plain pip command isn't on your PATH.

You'll use these steps again in the Weather App project and when installing Django.

Key points

  • python -m pip install name installs packages from PyPI.
  • python -m venv .venv creates an isolated environment for one project.
  • Activate with .venv\Scripts\Activate.ps1 (PowerShell), .venv\Scripts\activate.bat (cmd) or source .venv/bin/activate (macOS/Linux).
  • pip freeze > requirements.txt records versions; pip install -r requirements.txt recreates them.
  • Never commit or move the .venv folder; rebuild it instead.
Up next · Modules & PackagesCreating Your Own ModulesSplit a program across files.
→

Tip: use the ← and → keys to move between pages.