Isolate dependencies

What you will be able to do

Give the ticket-cleaner project its own Python environment, install a package into it, and write down the exact versions. Then the project runs the same next month, and on another person’s computer.

Before you startWhat to know and to have readyAbout 35 minutes

What you need to know

• What the interpreter is, and how to check which Python runs, from Install and verify Python.
• The working directory, from Files and terminal.

What you need on your computer

• Python 3.12 or newer, which runs when you type python3 (python on Windows). You installed it in Install and verify Python: Step 1. If the wrong Python runs, follow the common mistake “The wrong Python runs” on that page.
• first_run.py in ~/projects/ticket-cleaner. You made it in Install and verify Python: Guided practice. If it is missing, make it again from the worked example.
• VS Code with the Python extension, from Install and verify Python: Step 3. A different code editor also works.
• An internet connection. You download about 1 MB of packages.

Tested with Python 3.14 on macOS (pip 26.1), Windows in PowerShell, and Ubuntu 26.04 (pip 25.1).

Packages, and why each project needs its own

Python comes with a lot of ready-made code. For other work, you use packages: code that other people wrote and published. For example, the package httpx sends requests to websites, and the package pytest runs tests. You use both later in this course. Most packages come from the Python Package Index (PyPI), and you install them with a tool called pip.

A package that your project needs is a dependency of the project. Dependencies cause two problems when every project shares one Python:

• Versions clash. An older project needs httpx 0.27, and a new project needs 0.28. One Python can hold only one version at a time.
• The list gets lost. After a few months, nobody knows which packages this project needs and which belong to other projects. A new team member cannot set it up.

A virtual environment solves both. It is a folder in your project, usually called .venv, with its own link to the interpreter and its own place for packages. Packages that you install into it are visible only in this project. The Python that you installed in the previous lesson does not change.

The editor and the terminal must both use the interpreter in .venv. Then the code finds the packages that you installed for this project.

Text description of the diagram

The terminal runs python first_run.py. Because the environment is activated, python means the interpreter inside .venv. That interpreter reads the script from the project folder, and when the script imports a package, it looks in .venv. The editor has its own setting for the interpreter (dotted line), which must point to the same .venv. If the terminal or the editor uses a different interpreter, the packages in .venv are not found.

To use an environment in a terminal, you activate it. Activation changes that terminal, so the python command means the interpreter in .venv. It stays active until you close the terminal or run deactivate. The terminal prompt starts with (.venv) while it is active.

Worked example: make and use an environment

Amira makes an environment for ticket-cleaner. The -m venv part tells Python to run its built-in venv tool. The last argument is the name of the folder to make.

macOS

Terminal

cd ~/projects/ticket-cleaner
python3 -m venv .venv
source .venv/bin/activate

Windows

PowerShell

cd ~/projects/ticket-cleaner
python -m venv .venv
.venv\Scripts\Activate.ps1

Linux

Terminal

cd ~/projects/ticket-cleaner
python3 -m venv .venv
source .venv/bin/activate

The prompt now starts with (.venv). From here, she types python on every system, because activation made python point to the environment. She checks which interpreter runs:

Terminal

python -c "import sys; print(sys.executable)"

Output (macOS)

/Users/amira/projects/ticket-cleaner/.venv/bin/python

The path is inside the project folder. On Windows, it ends with ticket-cleaner\.venv\Scripts\python.exe.

Next, she installs httpx, at an exact version. == means “exactly this version”. She runs pip through the interpreter with python -m pip, so the package goes into the environment of that interpreter and nowhere else:

Terminal

python -m pip install httpx==0.28.1

Output (last line)

Successfully installed anyio-4.15.1 certifi-2026.7.22 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 idna-3.20 typing_extensions-4.16.0

She asked for one package, and pip installed seven. httpx has its own dependencies, and pip installed them too. If pip also shows a notice that a new version of pip is available, she can ignore it.

To see the difference, she leaves the environment and tries the same import with the computer’s Python:

Terminal

deactivate
python3 -c "import httpx"

Output

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import httpx
ModuleNotFoundError: No module named 'httpx'

This is the isolation working. httpx exists only in .venv. She activates the environment again before she continues.

Record the versions

Amira writes down what the project needs, so another person (or Amira, next month) can make the same environment. She uses two files:

File	Contents	Who writes it
requirements.txt	The packages that the project uses directly, with the versions that she chose.	You, by hand.
requirements-lock.txt	Every package in the environment, with its exact version, including the dependencies of dependencies.	pip, with pip freeze.

In VS Code, she makes requirements.txt with one line:

requirements.txt

httpx==0.28.1

Then she makes the lock file. The > sends the output of the command into a file instead of to the screen:

Terminal

python -m pip freeze > requirements-lock.txt

requirements-lock.txt

anyio==4.15.1
certifi==2026.7.22
h11==0.16.0
httpcore==1.0.9
httpx==0.28.1
idna==3.20
typing_extensions==4.16.0

Why both? requirements.txt is short and shows your decisions. When you want a newer httpx, you change one line there. The lock file shows exactly what was installed, so a new environment gets the same versions of all seven packages, not only httpx. Your versions can be newer than these. That is the reason to record them.

Note

Newer tools, such as uv, and a newer lock-file format, pylock.toml, do the same job with more features. The two-file method in this lesson uses only Python and pip, so it works everywhere. The idea is the same in every tool: list what you need, and lock what you got.

Make the environment again from nothing

An environment is disposable. It contains thousands of files that pip can make again. So you do not copy it to another computer, and you do not save it in Git. The lock file is what you keep. To prove that the lock file works, Amira deletes the environment and makes it again.

Caution

The delete command removes the folder and everything in it, with no recycle bin. Check that you are in the ticket-cleaner folder before you run it, and type .venv exactly.

macOS

Terminal

deactivate
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-lock.txt

Windows

PowerShell

deactivate
Remove-Item -Recurse -Force .venv
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements-lock.txt

Linux

Terminal

deactivate
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-lock.txt

The -r option means “read the package list from this file”. pip installs the same seven versions. This is also your reset: if an environment gets into a bad state, delete it and make it again from the lock file.

If you use Git (see the Git course), add a file called .gitignore to the project with the line .venv/. Git then does not track the environment. You commit requirements.txt and requirements-lock.txt.

Tell the editor which interpreter to use

VS Code runs and checks your code with its own interpreter setting. Set it to the environment, so the editor and the terminal agree.

1. In VS Code, open the ticket-cleaner folder.
2. Press Ctrl+Shift+P (Cmd+Shift+P on macOS).
3. Type Python: Select Interpreter, then press Enter.
4. Select the entry that shows .venv.
5. Open a new terminal with Terminal › New Terminal. VS Code activates the environment for you, and the prompt starts with (.venv).

Guided practice: set up ticket-cleaner

Do the worked example on your own computer.

1. Move to the project folder: cd ~/projects/ticket-cleaner.

2. Make the environment: python3 -m venv .venv (python -m venv .venv on Windows).

3. Activate it. On macOS and Linux, run source .venv/bin/activate. On Windows, run .venv\Scripts\Activate.ps1.

   The prompt starts with (.venv). If Windows shows an error about running scripts, see the second common mistake below.

4. Check the interpreter:

   python -c "import sys; print(sys.executable)"

   The path contains ticket-cleaner and .venv.

5. Install the package: python -m pip install httpx==0.28.1.

   The last line starts with Successfully installed.

6. Make requirements.txt with the line httpx==0.28.1.

7. Make the lock file: python -m pip freeze > requirements-lock.txt.

8. Run your first script again: python first_run.py.

   The Interpreter: line now shows the path inside .venv.

Your turn: a second project

Make a second project, ~/projects/env-practice, with its own environment. Install httpx version 0.27.2 in it. Then make a script check_httpx.py in both projects:

check_httpx.py

import sys

import httpx

print("Interpreter:", sys.executable)
print("httpx version:", httpx.__version__)

Run the script in each project, with that project’s environment active. Predict both outputs first.

Show the expected result

In env-practice, the script shows the interpreter in env-practice/.venv and httpx version: 0.27.2. In ticket-cleaner, it shows ticket-cleaner/.venv and 0.28.1. Two versions of the same package exist on one computer, and neither project affects the other. Remember to run deactivate before you move to the other project, then activate that project’s environment.

Common mistake

No module named …

Symptom: you run a script, and it stops with this error, although you installed the package:

ModuleNotFoundError: No module named 'httpx'

Cause: the script runs with a different interpreter than the one where you installed the package. Usually the environment is not active in this terminal: a new terminal does not activate it, and the prompt has no (.venv). In VS Code, the Run button can also use a different interpreter than the terminal.

Fix:

1. Check the interpreter: python -c "import sys; print(sys.executable)".
2. If the path is not in your project’s .venv, activate the environment, and run the script again.
3. If the path is correct, the package is not in this environment. Install it from the lock file: python -m pip install -r requirements-lock.txt.
4. In VS Code, select the .venv interpreter again (see above).

Do not fix this error by installing the package with a different pip until it works. That puts packages in several places, and the next error is harder to find.

Common mistake

Running scripts is disabled (Windows)

Symptom: on Windows, the activate command shows an error like this, and the prompt does not change:

.venv\Scripts\Activate.ps1 cannot be loaded because running scripts is disabled on this system.

Cause: PowerShell does not run script files by default. The activate command is a script file.

Fix: allow scripts that you made on your own computer, for your user account only. Run this once:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Type Y if PowerShell asks you to confirm, then run .venv\Scripts\Activate.ps1 again. If your computer is managed by your employer, the setting can be locked. In that case, ask your IT team. Or open Command Prompt instead of PowerShell, and run .venv\Scripts\activate.bat.

error: externally-managed-environment

On Linux, and with Python from Homebrew on macOS, pip install outside an environment stops with error: externally-managed-environment. This is a protection: the system’s own tools use that Python, and pip must not change it. The fix is the method in this lesson. Activate your project’s environment, then install.

Check your understanding

You open a new terminal, move to ticket-cleaner, and run python first_run.py. The Interpreter line shows a path that is not in .venv. Why, and what do you do?

Show the answer

A new terminal does not activate the environment, so python means the computer’s Python (or there is no python command, on macOS and Linux). Activate the environment with source .venv/bin/activate (.venv\Scripts\Activate.ps1 on Windows), check that the prompt starts with (.venv), and run the script again.

Check your understanding

A teammate sends you a project with requirements.txt and requirements-lock.txt, but no .venv folder. Is something missing? How do you set it up?

Show the answer

Nothing is missing. The environment is not shared, because it can be made again. Make an environment in the project folder, activate it, and run python -m pip install -r requirements-lock.txt. You get the same version of every package as your teammate.

Check your understanding

Module check: in a new terminal, show which interpreter and environment run in ticket-cleaner. Then deactivate the environment, run check_httpx.py, and fix the error that you see without installing anything new.

Show the answer

With the environment active, python -c "import sys; print(sys.executable)" shows a path in ticket-cleaner/.venv, and the prompt starts with (.venv). After deactivate, python3 check_httpx.py stops with ModuleNotFoundError: No module named 'httpx', because the computer’s Python does not have httpx. The fix is to activate the environment again, not to install httpx somewhere else. Then the script shows httpx version: 0.28.1.

Recap

• A dependency is a package that your project needs. pip installs packages from PyPI.
• A virtual environment (.venv) gives a project its own packages. Activate it in each new terminal. The prompt shows (.venv).
• Install with python -m pip install name==version, so the package goes into the active environment.
• requirements.txt lists what you chose. requirements-lock.txt (from pip freeze) records every exact version. Keep both, and make the environment again from the lock file when you need to.
• If a module is not found, check sys.executable before you install anything.

You can now set up a Python project that another person can make again. In the next module, you start to write Python: values, collections, decisions and loops.

Next: Basic values