Using UV

Details how to set up a Python evironment using UV.

For the latest on UV installation and use visit the official site.

Official site

docs.astral.sh/uv/

Install

Start with a base Python environment then install UV.

UV will install Python when you run uv venv even if you do not have Python installed. UV is able to manage Python installs and versions.

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

If you are using a VSCode Dev Container you can run this command in the postCreateCommand of your devcontainer.json or you can run it manually after the container is built.

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

Initial project set up

# cd into your project directory then
uv init

This will create a pyproject.toml, .python-version and main.py.

Workflow

Install all dependencies with uv sync
Make changes, add packages, etc
Run app with uv run .... Example: uv run uvicorn app.main:app --reload
Commit and push updates according to your source control workflow

You do not need to activate a virtual environment. As long as you use the uv command it will handle that for you.

Common commands

Version

uv --version

Init

# cd into your project directory then
uv init

Create .venv

uv will create the .venv folder as needed so you do not need to create it, but you can if you want to recreate it.

uv venv

You can also activate the venv with source .venv/bin/activate, but you do not need to do this if you are using the uv command. You would do this if you wanted to run the app without the uv run command.

Install all dependencies

uv sync

Run app

# Example running a fastAPI app with uvicorn
uv run uvicorn app.main:app --reload

It is possible to run the app without the uv run

# Activate the env
source .venv/bin/activate
# run app locally and reload on code changes
uvicorn app.main:app --reload
# the app will run under http://127.0.0.1:8000
# deactivate venv if you want
deactivate

Install package

uv add package-name

Install from requirements.txt

uv add -r requirements.txt

This will install all packages in the requirements.txt as you added them with the add command. So all the packages listed in the requirements.txt will appear in the pyproject.toml.

Remove package

uv remove package-name

Update UV

# if you installed it using the installer script
uv self update

If you installed it another way (pip, winget, homebrew, etc) then use the original install method to udpate UV.

See dependency tree

uv tree