uv to manage packages

25 May 2025

I have replaced poetry in enough projects now to be able to cover off uv

Generally speaking I will have already set up a git repo so I use the following to get started

# No git repo req'd hence the vcs flag

uv init \
--name $PROJECT_NAME \
--vcs none \ 
--python 3.13.2 \
.

Once that is done we then need to ask uv to set up a venv in .venv for us with e.g.

uv venv \
--python 3.13.2 \
".venv"

To run anything within your project, automatically making use of the venv, you can use

uv run python src/main.py

where src/main.py is the path of the python script you want to run

To add new packages is as simple as:

uv add package-name

where package-name is the name of the package

My vanilla makefile is below:

.POSIX:

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

NAME = project_name
PYTHON = 3.13.2
PREPEND = uv run
VENV = .venv

run:
	$(PREPEND) python src/main.py

modules:
	uv pip list

format:
	$(PREPEND) python -m black ./src/*.py ./tests/*.py
	$(PREPEND) python -m isort ./src/*.py ./tests/*.py

test:
	$(PREPEND) pytest

cursor:
	uv run cursor .

bootstrap:
	@printf "uv init \\ \n \
	--name $(NAME) \\ \n \
	--vcs none \\ \n \
	--python $(PYTHON) \\ \n \
	. \n"

venv:
	uv venv \
	--python $(PYTHON) \
	$(VENV)

install:
	uv pip install .

activate:
	@echo source $(VENV)/bin/activate

Setting up uv where pyproject.toml already exists

If you’re not setting up a new project and are e.g. cloning a repo to a machine fresh

(here assuming python version is 3.13.3)

# if 3.13.3 not yet installed
# uv python install 3.13.3
uv venv --python 3.13.3 ".venv"
source .venv/bin/activate
uv pip install -r pyproject.toml