Pirate Wiki

Toggle Theme

uv: A Fast, All-in-One Package Manager ​

uv is a Python package and project manager, written in Rust. It aims to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more.

Installation ​

There are many you can install uv, refer to this official guide for different installation methods.

**You can confirm the installation by running uv command in the terminal.

Project Management ​

To create a new Python project, run the following command:

shell
# new_project is optional and creates a projects inside a new directory.
# If you want to create the project in current directory, you can omit it.
uv init <new_project>

Project Types ​

There are different project types that uv supports:

NOTE

Except for --bare and --script options below, uv initializes a git version control system in all directories.

Applications ​

shell
uv init <new_app>

# OR (Explicit Option)
uv init --app <new_app>

This is the default project type of uv init command. It creates a directory with the following files:

  • .python-version
  • README.md
  • main.py
  • pyproject.toml

This is ideal for standalone applications, that don't require a build system and need not be installed into the environment.

Scripts ​

shell
uv init --script <new_script>

This creates a single file new_script.py in the current directory. This is ideal for standalone scripts or one-off programs that need isolated environments without full project setup.

Bare/Minimal Projects ​

shell
uv init --bare <new_bare_project>

This creates a project directory with just the pyproject.toml file. This provides a minimal starting point for custom project setups.

Libraries ​

shell
uv init --lib <new_library>

This is used for creating a project, that's meant to be packaged and distributed for reusability (For imports in other packages). This command creates the following files:

shell
new_library
├── pyproject.toml
├── README.md
└── src
    └── new_library
        ├── __init__.py
        └── py.typed

As shown above, this command creates a py.typed file for type hinting support.

Packages ​

shell
uv init --package <new_package>

This is very similar to the --lib option, with the following differences:

  • Package doesn't include py.typed file.
  • It includes command entry points in pyproject.toml file, unlike libraries.

Virtual Environments ​

Unlike pip, uv requires using a virtual environment by default. And unlike older way of activating tha virtual environment manually, uv creates and manages the virtual environment automatically for you. You can, however, explicitly create it using:

shell
# new_venv is optional, when not provided .venv is used.
uv venv <new_venv>

To run a command in the project environment, use the command:

shell
uv run

Lock File ​

uv supports locking dependencies using the uv.lock file. This file records the exact versions of all packages installed, including the sub-dependencies. This ensures that your environment is perfectly re-producible.

If you want to create this lock file explicitly, say for scripts, you can do so by using:

shell
uv lock --script my_script.py

To visualize all dependencies in your project, you can use the following command:

shell
uv tree

To add or remove dependencies, use following commands:

  • uv add: Add a dependency to the project.
  • uv remove: Remove a dependency from the project.

If you want to recreate the environment on a different system, you can use this command:

shell
uv sync

NOTE

uv uses a global caching system. That is, if multiple projects use same version of a package, it is stored only once on the disk by uv, which is very storage-efficient.

Manage Python Versions ​

You don't need Python installed to get started with uv. Also, if Python is already installed on your system, uv will detect and use it without configuration. However, uv can also install and manage Python versions.

To install Python, use following command:

shell
# version is optional, when omitted the latest version is installed.
uv python install <version>

# You can also install multiple versions.
uv python install 3.11 3.12

NOTE

When Python is installed by uv, it will not be available globally (i.e. via the python command). For now, you'll need to use --python option with various uv commands, to specify the Python version.

To view available and installed Python versions, use:

shell
uv python list

The pip interface ​

uv provides a drop-in replacement for common pip, pip-tools, and virtualenv commands. The uv pip interface exposes the speed and functionality of uv to power users and projects that are not ready to transition away from pip and pip-tools.

Replacing pip:

  • uv pip install: Install packages into the current environment.
  • uv pip show: Show details about an installed package.
  • uv pip freeze: List installed packages and their versions.
  • uv pip check: Check that the current environment has compatible packages.
  • uv pip list: List installed packages.
  • uv pip uninstall: Uninstall packages.
  • uv pip tree: View the dependency tree for the environment.

Replacing pip-tools:

  • uv pip compile: Compile requirements into a lockfile.
  • uv pip sync: Sync an environment with a lockfile.

Tools ​

Many Python packages provide applications that can be used as tools. uv has specialized support for easily invoking and installing tools. Some of these tools are useful across all projects and environments on the same system. Examples include ruff, black etc.

Here are the most common commands for uv tools:

  • uvx / uv tool run: Run a tool in a temporary environment.
  • uv tool install: Install a tool user-wide.
  • uv tool uninstall: Uninstall a tool.
  • uv tool list: List installed tools.
  • uv tool upgrade --all: Upgrade all installed tools.
  • uv tool update-shell: Update the shell to include tool executables (That is, it adds the tool to the PATH variable).

NOTE

uvx is an alias for uv tool run, provided for convenience.

Utility ​

Managing and inspecting uv's state, such as the cache, storage directories, or performing a self-update:

  • uv cache clean: Remove cache entries.
  • uv cache prune: Remove outdated cache entries.
  • uv cache dir: Show the uv cache directory path.
  • uv tool dir: Show the uv tool directory path.
  • uv python dir: Show the uv installed Python versions path.
  • uv self update: Update uv to the latest version.

Building and Publishing Packages ​

uv supports building Python packages into source and binary distributions via uv build and uploading them to a registry with uv publish.

Before attempting to publish your project, confirm that pyproject.toml includes [build-system] definition.

By default, uv build will build the project in the current directory, and place the built artifacts in a dist/ subdirectory. Alternatively, uv build <SRC> will build the package in the specified directory.

For publishing a package, set the token using --token option or pass credentials using --username/--password options. If you're using a custom index through [[tool.uv.index]], add publish-url and use uv publish --index <name> command.

NOTE

PyPI does not support publishing with username and password anymore, instead you need to generate a token. Using a token is equivalent to setting --username __token__ and using the token as password.

Testing the package installation ​

To test that the package can be installed and imported, use:

shell
uv run --with <PACKAGE> --no-project -- python -c "import <PACKAGE>"

The --no-project flag is used to avoid installing the package from your local project directory.

TIP

If you have recently installed the package, you may need to include the --refresh-package <PACKAGE> option to avoid using a cached version of the package.