Virtual environments: Python for services

One private set of libraries for each project, so that projects can never disturb each other.

Suppose Project A needs version 1 of a library, and Project B needs version 2. Your computer has only one place where Python looks for installed libraries. Installing version 2 for B breaks A. This is the second cause of "it works on my machine".

The fix is to give each project its own private set of libraries.

Virtual environment

A folder (usually named .venv) that holds its own link to Python and its own installed libraries. Installing a library into it does not touch any other project or the Python that came with your computer. You can delete the folder at any time and rebuild it.

Each project gets its own environment, so version conflicts between projects cannot happen.

Create one and use it

$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python --version
Python 3.13.16

python -m venv .venv creates the folder .venv in the current directory.
source .venv/bin/activate activates it. The (.venv) at the start of your prompt shows that it is active. While it is active, the commands python and pip use the copies inside .venv.

You can see the effect:

(.venv) $ which python
/home/asha/triage-service/.venv/bin/python
(.venv) $ deactivate
$ which python
/usr/bin/python

Your paths will differ. deactivate turns the environment off.

On Windows the commands differ

In Command Prompt: .venv\Scripts\activate
In PowerShell: .venv\Scripts\Activate.ps1. If PowerShell says that running scripts is disabled, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once and try again.
If python is not found, try py -m venv .venv. The py command is the Python launcher that the Windows installer provides.
where python is the Windows version of which python.

Now install a library. It goes into .venv only:

(.venv) $ python -m pip install pydantic
(.venv) $ python -m pip list
Package           Version
----------------- -------
annotated-types   0.8.0
pydantic          2.14.2
pydantic_core     2.50.2
...

Notice that you asked for one package and got several. pydantic needs the others to work, and pip installed them for you. That idea is next.

Check yourself

What problem does a virtual environment solve?
How can you tell that an environment is active?
You break an environment by installing the wrong thing. What is the quickest fix?

For the curious Pin the Python version too, and a faster tool called uv

Libraries support only some Python versions. Choose one for the project (for example 3.12), write it in pyproject.toml as requires-python (next part), and install exactly that version with a version manager such as pyenv or uv.

uv is a newer tool that does the work of venv, pip and a version manager, and does it much faster: uv venv, uv pip install, uv sync, and uv python install. The ideas are identical, so learn them with the standard tools first and move to uv when you want speed.