0%

Virtual Environment via UV

November 15, 2025

Python

Contents

1. uv

1.1. Introduction

UV is a package manager that can replace the virtual environment manager such as conda and pyenv.

1.2. Installation

For mac user we simply execute:

curl -LsSf https://astral.sh/uv/install.sh | sh

We can execute uv --version to check whether uv is installed.

1.3. pyproject.toml and .python-version

1.3.1. uv sync from existing pyproject.toml

With the presence of

  1. pyproject.toml for definition all dependencies and their version
  2. .python-version for definition of python version

we can execute

uv sync

to install all specified dependences. The directory .venv/ will be created to install everything needed to launch a virtual environment.

1.3.2. add specific package

The command

uv add package_name

will automatically update the pyproject.toml and uv.lock for for us (just like package.json and package.lock.json).

1.4. How to Set the name of the Virtual Environment Generated by a uv project

We execute

uv project metadata --set name="agents"

It will set a value in pyproject.toml:

Now we can select agents from the python interpretor or from the kernels of jupyter notebook.

1.5. How to Generatge the good old requirement.txt if we still need it?

The file requirement.txt is not strictly necessary if we are using uv throughoutly. If someone is still using conda or pyenv for virtual environments, then export one for them:

uv pip compile pyproject.toml -o requirements.txt

2. Virtual Environment by uv

2.1. What uv sync does

uv automatically manages a virtual environment:

  • ✅ Creates a .venv directory (or custom location)
  • ✅ Installs all dependencies there
  • ✅ Isolates your project from system Python
  • ✅ You don't manually create it—uv sync does

The command

uv sync

automatically:

  1. Creates or updates .venv/
  2. Installs all dependencies from pyproject.toml
  3. Ready to use

2.2. Execute python Script in uv virtual environment

python something.py is now replaced by

uv run something.py