pip & Virtual Environments
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
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.
.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 shell | Activate 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)"
When you're finished, type deactivate to return to the normal system Python.
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:
| Specifier | Meaning |
|---|---|
django==5.1.4 | Exactly this version |
django>=5.0 | 5.0 or newer |
django>=5.0,<6.0 | Any 5.x version |
django~=5.1.0 | Compatible 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
- Create a project folder and
cdinto it. - Run
python -m venv .venv. - Activate the environment (check for
(.venv)in the prompt). - Install packages with
python -m pip install .... - Save them with
python -m pip freeze > requirements.txt. - If you use Git, add
.venv/to your.gitignorefile and commitrequirements.txtinstead.
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.
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.
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.
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 nameinstalls packages from PyPI.python -m venv .venvcreates an isolated environment for one project.- Activate with
.venv\Scripts\Activate.ps1(PowerShell),.venv\Scripts\activate.bat(cmd) orsource .venv/bin/activate(macOS/Linux). pip freeze > requirements.txtrecords versions;pip install -r requirements.txtrecreates them.- Never commit or move the
.venvfolder; rebuild it instead.
Tip: use the ← and → keys to move between pages.
