Python Virtual Environments and pip

A virtual environment is a private folder of packages for one project, so different projects never fight over versions.

The Problem

Suppose Ali builds a shop website that needs version 2 of a package. Later he starts a school project that needs version 3. If both projects use the same Python on his laptop, upgrading for one project can break the other.

A virtual environment (often called a venv) solves this. Each project gets its own copy of Python's package folder. Packages installed inside it stay inside it.

Step 1: Create the Environment

Open a terminal in your project folder and run:

cd shop-project
python -m venv .venv

This creates a folder called .venv with its own python and pip. The name .venv is a common choice, and most editors detect it automatically.

Step 2: Activate It

Activating tells your terminal to use the environment's Python and pip.

After activation, the prompt shows the environment name in brackets:

(.venv) C:\Users\Ali\shop-project>

You can check which Python is now in use. On Linux it looks like this:

which python
python --version

/home/ali/shop-project/.venv/bin/python
Python 3.13.16

On Windows use where python instead of which python.

Step 3: Install Packages

With the environment active, pip install puts packages only into .venv.

pip install requests
pip list

Successfully installed certifi-2026.7.22 charset_normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0
Package            Version
------------------ ---------
certifi            2026.7.22
charset-normalizer 3.5.2
idna               3.20
pip                26.2.1
requests           2.34.2
urllib3            2.8.0

requests needed four other packages (its dependencies), and pip installed them automatically.

More pip Commands

Step 4: Save Your Requirements

pip freeze prints every installed package with its exact version. Save it in a file so others can build the same environment.

pip freeze > requirements.txt

The file requirements.txt now contains:

certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
urllib3==2.8.0

When your friend Sara downloads the project, she creates her own venv and installs everything in one line:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Step 5: Deactivate

When you finish working, leave the environment:

deactivate

The brackets disappear from the prompt, and python points to the main system Python again.

Do Not Share the .venv Folder

The .venv folder can be hundreds of megabytes and only works on the computer that made it. Never email it or upload it to GitHub. Share requirements.txt instead. Add this line to your .gitignore file:

.venv/

A Typical Project Layout

shop-project/
    .venv/               (not shared)
    .gitignore
    requirements.txt
    main.py
    shop.py
    test_shop.py

A Faster Modern Tool: uv

In 2026 many teams use uv, a very fast tool that creates the environment and manages packages for you. It keeps the list of packages in a file called pyproject.toml.

pip install uv
uv init shop-project
cd shop-project
uv add requests
uv run main.py

uv add creates .venv if needed and installs the package in a moment:

Prepared 6 packages in 70ms
Installed 6 packages in 2ms
 + certifi==2026.7.22
 + charset-normalizer==3.5.2
 + idna==3.20
 + requests==2.34.2
 + urllib3==2.8.0

uv run runs your file inside the project's environment, so you do not even need to activate it. Learn plain venv and pip first, because every Python setup understands them, then try uv on your next project.

Exercise