Skip to main content

Programming languages · Beginner · 14 min

How to Use Virtual Environments and Install Packages in Python

By Padding · Updated 15 Nov 2026
Python 3.15 · uv 0.13

You will create an isolated Python 3.15 environment for a project, install a package into it with pip, record the exact versions, rebuild the environment from that record, and then manage the same project with uv.

On this page

Python projects depend on packages, which are libraries other people published on PyPI, the Python Package Index. If every project installed its packages into the same place, two projects that need different versions of one library would break each other. A virtual environment fixes this. It is a folder holding its own copy of the Python interpreter and its own packages, used by one project only.

This tutorial shows the built-in way first, python -m venv with pip, because every Python installation has it and you will meet it in nearly every guide and CI file. Then it shows the same job with uv, which is faster and keeps a lock file. It assumes you installed Python 3.15 and uv in the first tutorial of this series.

Step 1 · Create and activate an environment

Make a project folder, then create an environment named .venv inside it. The dot at the start of the name hides it from normal file listings. Using that name is a convention that editors and tools look for:

Bash
mkdir -p ~/venv-demo
cd ~/venv-demo
python3.15 -m venv .venv

The folder .venv/ now holds a Python 3.15 interpreter and pip. Activate it, which puts that interpreter first on your path for this shell:

Bash
source .venv/bin/activate
which python
python --version

Check it worked

which python prints a path ending in /venv-demo/.venv/bin/python, and python --version prints Python 3.15. and a patch number. While the environment is active, your prompt usually starts with (.venv). Only the shell you activated in is affected, so a second terminal still uses its own default Python.

Step 2 · Install a package with pip

Install rich, a library that prints coloured and formatted text in the terminal. Pin the version, so that you and anyone else who follows this get the same one:

Bash
pip install rich==15.0.0

pip downloads rich and the libraries it depends on. See what is installed, and use the package:

Bash
pip freeze
python -c "from rich import print; print('[bold green]It works[/bold green]')"

Check it worked

pip freeze lists rich==15.0.0 and its dependencies, something like markdown-it-py, mdurl and Pygments, each with an exact version. The python -c line prints It works, in bold green if your terminal supports colour.

Troubleshooting

If pip install reports externally-managed-environment, you are not inside the virtual environment, and you are talking to the operating system's own Python, which Debian and Ubuntu protect on purpose (PEP 668). Activate .venv first, and never use --break-system-packages as a shortcut. If pip says it cannot find a version, check the spelling of the package and the version number on pypi.org.

Step 3 · Record the versions

A file listing exact versions lets someone else rebuild your environment. pip freeze writes it in the format pip install -r reads:

Bash
pip freeze > requirements.txt
cat requirements.txt

Then leave the environment and delete it. The folder is disposable. It can always be rebuilt, so it does not belong in Git. Commit requirements.txt and add .venv/ to .gitignore.

Bash
deactivate
rm -rf .venv

Step 4 · Rebuild the environment with uv

Now recreate the same environment from the file, using uv. uv venv makes .venv as before, and uv pip install takes the same arguments as pip install, but runs far faster:

Bash
uv venv --python 3.15
uv pip install -r requirements.txt
uv pip list

uv venv finds your Python 3.15 and prints Creating virtual environment at: .venv. You do not need to activate the environment to use it with uv. uv run finds .venv in the current folder:

Bash
uv run python -c "import rich; print(rich.__file__)"

Check it worked

uv pip list shows the same four packages and versions as requirements.txt. The rich.__file__ path points inside .venv/lib/python3.15/site-packages/.

Step 5 · Let uv manage a whole project

requirements.txt records versions, but not what you asked for, and it does not tell apart your own packages from their dependencies. uv's project mode keeps both in pyproject.toml, the standard Python project file, plus a lock file. Start a fresh project:

Bash
cd ~
mkdir -p uv-demo
cd uv-demo
uv init --no-package

--no-package makes a plain application, not a library you would publish. uv creates four files: pyproject.toml, main.py, README.md and .python-version. Add a dependency:

Bash
uv add rich

uv creates .venv/ on first use, installs rich, adds it to the dependencies list in pyproject.toml, and writes uv.lock with the exact version of every package it resolved. Replace the generated main.py with a script that uses the package, and run it:

Bash
cat > main.py <<'PY'
from rich.table import Table
from rich.console import Console

table = Table(title="Environments")
table.add_column("Tool")
table.add_column("Job")
table.add_row("venv", "isolate packages")
table.add_row("pip", "install packages")
table.add_row("uv", "do both, and lock versions")

Console().print(table)
PY
uv run main.py

uv run checks that .venv matches the lock file, fixes it if it does not, and then runs the script. You never activate anything. See what depends on what, then remove a package you no longer use:

Bash
uv tree
uv remove rich
cat pyproject.toml

Check it worked

uv run main.py prints a small table titled Environments with three rows. uv tree shows rich with markdown-it-py and pygments below it. After uv remove rich, the dependencies list in pyproject.toml is empty again.

Commit pyproject.toml, uv.lock and .python-version. On another machine, uv sync recreates the same environment from them. Keep .venv/ out of Git.

Step 6 · Clean up

Remove the demo folders. Only your own folders are deleted. Python 3.15 and uv stay installed:

Bash
cd ~
rm -rf ~/venv-demo ~/uv-demo

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.