UV Cheat Sheet incorporating the latest tips and tricks from the official UV documentation:

UV Cheat Sheet

Installation

Install UV using the official standalone installer:

macOS and Linux:

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

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Tip: UV can also be installed via pip, Homebrew, and other methods. Refer to the installation page for more options.

Project Management

Initialize a New Project

Create a new project in a specified directory:

uv init <project_name>

If the directory already exists:

cd <existing_project>
uv init

This sets up a pyproject.toml and a .venv directory for the virtual environment.

Add Dependencies

Install a new dependency:

uv add <package_name>

Install multiple dependencies from a requirements.txt file:

uv add -r requirements.txt

Add a development-only dependency:

uv add --dev <package_name>

Tip: To install a package from a specific source, such as a Git repository:

uv add "package_name @ git+https://github.com/user/repo"

For more details, see the Managing Dependencies section.

Update Dependencies

Update all dependencies to their latest compatible versions:

uv update

To upgrade a specific package:

uv add <package_name> --upgrade-package <package_name>

Remove Dependencies

Remove a specific dependency:

uv remove <package_name>

Environment Management

Running Scripts

Run a script using the UV-managed environment:

uv run <script_name.py>

To run a command or tool:

uv run <command> [args...]

Tip: UV supports running scripts with inline dependency metadata. For more information, refer to the Running Scripts guide.

Activating the Environment

Manually activate the virtual environment:

source .venv/bin/activate

Checking Environment Status

Check the environment and project configuration:

uv status

Custom Virtual Environment Directory

Set a custom path for environments by defining the UV_PROJECT_ENVIRONMENT environment variable:

export UV_PROJECT_ENVIRONMENT=/path/to/custom_env

If a relative path is provided, it will be resolved relative to the workspace root. For more details, see the Configuring Projects section.

Global Tools Management

Manage globally installed Python tools (e.g., black, flake8):

uv tool install <tool_name>
uv tool uninstall <tool_name>

List installed tools:

uv tool list

Tip: To run a tool in an ephemeral environment without installing it globally:

uvx <tool_name> [args...]

uvx is an alias for uv tool run. For more information, refer to the Using Tools guide.

Building and Publishing

Build the Project

Package your project for distribution:

uv build

This command creates source distributions and wheels in the dist/ directory.

Publish the Project

Upload distributions to an index (e.g., PyPI):

uv publish

To specify a different index:

uv publish --index <index_name>

Note: Ensure that your pyproject.toml includes the appropriate [tool.uv.index] configuration for custom indexes. For more details, see the Publishing Packages guide.

Advanced Configuration

Using a Specific Python Version

Specify the Python version for your project:

uv init --python <python_version>

Example:

uv init --python 3.11

UV will search for an interpreter that meets the request. If it finds a system interpreter (e.g., /usr/lib/python3.12), the --system flag is required to allow modification of this non-virtual Python environment. For more information, refer to the Using Environments section.

Customizing Package Indexes

To add Python packages from a specific index:

uv add <package_name> --index <index_name>=<index_url>

Define the index in your pyproject.toml:

[[tool.uv.index]]
name = "<index_name>"
url = "<index_url>"

For more details on configuring indexes and authentication, see the Package Indexes section.

Tips and Tricks

Editable Installations: To install the current project as an editable package:
```
uv pip install -e .
```
For more information, refer to the Managing Packages section.
Handling Build Failures: If you encounter build failures, ensure that all necessary build tools and libraries are installed on your system. For troubleshooting, see the Build Failures reference.
Running Scripts with Inline Dependencies: UV supports running scripts that specify their dependencies inline. This allows for isolated environments tailored to each script. For more details, see the Running Scripts guide.
Using Workspaces: For projects with multiple packages, UV supports Cargo-style workspaces for scalable project management. Refer to the Using Workspaces documentation for setup and usage.

For comprehensive documentation, visit the UV Documentation.

flight505/UV_Cheat_Sheet.md