---
title: 'Project Management with UV'
url: 'https://gerfficient.com/en/home/python-uv'
markdown: 'https://gerfficient.com/en/home/python-uv.md'
lang: en
date: '2025-11-21'
description: 'Some time ago, I published a post explaining how to create and manage a portable development environment in Python using venv. In combination with pyenv, this allows you to install modules and packages for a desired version of Python. uv is an extremely fast dependency and environment manager for P…'
---

# Project Management with UV

###  21. Nov. 2025 

Some time ago, I published a [post](https://gerfficient.com/en/home/python-developing) explaining how to create and manage a portable development environment in Python using `venv`. In combination with `pyenv`, this allows you to install modules and packages for a desired version of Python.

`uv` is an extremely fast dependency and environment manager for Python development. In this post, I summarize how to install `uv` and how to use it.

## Setup

The easiest way to install `uv` is with Homebrew:

```bash
brew install uv
```

However, direct [installation](https://docs.astral.sh/uv/#installation) is also possible:

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

## Usage

To highlight the advantages of using `uv`, I will later briefly show the old approach to managing dependencies in a Python environment and how to migrate a project set up in this way to a `uv` project.

### Approach with `uv`

A new project can be initialized with:

```bash
uv init APP_NAME
```

Alternatively, a `uv` project can be initialized in an existing folder by navigating to the folder and then entering the same command, but without a project name:

```bash
uv init
```

This creates a simple Python project, including version control with `git` (in the `.git` folder) and environment management (in the `.venv` folder). Arguments can also be specified during initialization, such as:

- `--app` with which an application is created, or
- `--lib` which is used to create a shareable library.

New dependencies are then installed with:

```bash
uv add xxxx
```

Dependencies can be deleted with:

```bash
uv remove xxx
```

The dependencies have now been installed and specified in the `pyproject.toml` file so that the `uv` environment can be shared. The dependencies can also be viewed with:

```brew
uv tree
```

Code is executed by `uv` with:

```bash
uv run main.py
```

If you now delete the virtual environment (i.e., the `.venv` folder), `uv` can continue to execute the code because it automatically reinstalls all dependencies in a virtual environment (referencing the `project.toml` file).

If you want to set up the virtual environment automatically without having to execute the code, you can do so with:

```bash
uv sync
```

To install a specific version of Python, use:

```bash
uv python install 3.10 3.11 3.12
```

And the version to be used can then be selected with:

```bash
uv python pin 3.11
```

Available versions of Python can be queried as follows:

```bash
uv python list
```

### The old approach

A virtual environment is created with:

```bash
python -m venv .venv
```

It is activated with:

```bash
source .venv/bin/activate
```

Dependencies are installed in the now activated environment using `pip` with:

```bash
pip install xxxx
```

To save the installed dependencies for later reproducibility, use the following command:

```bash
pip freeze > requirements.txt
```

The file obtained in this way can install dependencies in an environment (especially one that has not yet been set up) using:

```bash
pip install -r requirements.txt
```

Code (e.g., in a file named `main.py`) is then executed with:

```bash
python main.py
```

And the environment can be deactivated with:

```bash
deactivate
```

If you want to change the Python version, you must install `pyenv`, for example, so that the desired version can be installed and activated, and then set up the virtual environment (`.venv`) again as described above.

### Migration to `uv`

If you have a project set up with only `pip` (or `uv pip`), you can migrate it to `uv` by first initializing a `uv` project:

```bash
uv init
```

After that, all dependencies can be installed with:

```bash
uv add -r requirements.txt
```

The `requirements.txt` file is then no longer necessary and can be deleted.

---

## Navigation

- Parent: [Home](https://gerfficient.com/en/index.md)
- Previous: [LLM Model Formats, Conversion and Quantization](https://gerfficient.com/en/home/model-quantization.md)
- Next: [React in 2025](https://gerfficient.com/en/home/react-in-2025.md)