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:
mkdir -p ~/venv-demo
cd ~/venv-demo
python3.15 -m venv .venvThe folder .venv/ now holds a Python 3.15 interpreter and pip. Activate it, which puts that interpreter first on your path for this shell:
source .venv/bin/activate
which python
python --versionCheck 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:
pip install rich==15.0.0pip downloads rich and the libraries it depends on. See what is installed, and use the package:
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:
pip freeze > requirements.txt
cat requirements.txtThen 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.
deactivate
rm -rf .venvStep 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:
uv venv --python 3.15
uv pip install -r requirements.txt
uv pip listuv 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:
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:
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:
uv add richuv 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:
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.pyuv 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:
uv tree
uv remove rich
cat pyproject.tomlCheck 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:
cd ~
rm -rf ~/venv-demo ~/uv-demoNext steps
- Read and save data from your scripts: files and JSON in Python.
- Use a package from PyPI that talks to the web: call a web API with httpx.
- The uv documentation at docs.astral.sh/uv explains lock files, dependency groups and workspaces.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials