Getting Started

Installation

  • For Linux and macOS, install with:
curl -LsSf https://astral.sh/uv/install.sh | sh
  • Install with Homebrew:
brew install uv

Shell Autocompletion

  • Enable shell autocompletion for uv and uvx for Bash:
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc
  • Enable shell autocompletion for uv and uvx for Zsh:
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc

Utility

# Update uv to the latest version
uv self update
# Remove all cache entries
uv cache clean
# Remove outdated cache entries; safe to run periodically
uv cache prune
# Show the uv cache directory
uv cache dir
# Show the uv tool directory
uv tool dir
# Show the uv installed Python versions
uv python dir

Uninstallation

# Clean up stored data (optional)
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"
# Remove uv and uvx
rm ~/.local/bin/uv ~/.local/bin/uvx

Project

Create a Project

  1. Create a new Python project
uv init <project>
cd <project>
  1. Initialize a project in the working directory
mkdir <project>
cd <project>
uv init
  1. Pin the project to a specific Python version
cd <project>
uv python pin <version>

Project Structure

.
├── .venv             # Virtual environment
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version   # Default Python version
├── README.md
├── main.py
├── pyproject.toml    # Metadata (dependencies, license, etc.)
└── uv.lock           # Exact information of project dependencies

Manage Package

[!WARNING] It is not recommended to modify the project environment manually, e.g., with uv pip install.

# Add a package with a specific version
uv add '<package>==<version>'
# Add a git package
uv add git+<git_url>
# Add packages from `requirements.txt`
uv add -r requirements.txt
# Upgrade all packages
uv lock --upgrade
# Upgrade a specific package to the latest version
uv lock --upgrade-package <package>
# Upgrade a specific package to a specific version
uv lock --upgrade-package <package>==<version>
# Remove a package
uv remove <package>

Run Commands in a Project

# Run a Python file
uv run python <python_file>
# Run a `bash` script
uv run bash <script>

Lock and Sync

  1. Locking is the process of resolving the project’s dependencies into a lockfile.
  2. Syncing is the process of installing a subset of packages from the lockfile into the project environment. Syncing will remove any packages that are not present in the lockfile.
  3. Locking and syncing are automatic in uv. For example, when uv run is used, the project is locked and synced before invoking the requested command. This ensures the project environment is always up-to-date. Similarly, commands which read the lockfile, such as uv tree, will automatically update it before running.
# Create/Update the lockfile
uv lock
# Sync the environment
uv sync
# Export the lockfile to `requirements.txt`
uv export --format requirements-txt > requirements.txt

Python

# List installed and available Python versions
uv python list
# Find an installed Python version
uv python find <version>
# Install Python with a specific version
uv python install <version>
# Pin the project to a specific Python version
uv python pin <version>
# Uninstall a Python version
uv python uninstall <version>

Virtual Environment

uv venv basically can replace venv and virtualenv.

# Create a virtual environment with a apecific Python version
mkdir ~/envs/
uv venv ~/envs/<env> --python <version>
# Activate a virtual environment
source <env_dir>/bin/activate
# Deactivate a virtual environment
deactivate

The Pip Interface

uv pip basically can replace pip, pip-tools, and pipdeptree.

# Install a package
uv pip install '<package>==<version>'
# Install packages from `requirements.txt`
uv pip install -r requirements.txt
# Uninstall a package
uv pip uninstall <package>
# List installed packages
uv pip list
# View the dependency tree
uv pip tree
# Compile requirements into a lockfile
uv pip compile <source> -o requirements.txt
# Sync an environment with a lockfile
uv pip sync requirements.txt

References