### Install Latest uv with setup-uv Action

Source: https://docs.astral.sh/uv/guides/integration/github

Installs the latest version of uv using the official GitHub Action. This is the recommended way to get started.

```yaml
name: Example

jobs:
  uv-example:
    name: python
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

```

--------------------------------

### Example: Install Ansible with executables from related packages

Source: https://docs.astral.sh/uv/concepts/tools

This example demonstrates installing Ansible and including executables from `ansible-core` and `ansible-lint` into the same environment.

```bash
$ uv tool install --with-executables-from ansible-core,ansible-lint ansible
```

--------------------------------

### Install and Run a Tool

Source: https://docs.astral.sh/uv/guides/integration/docker

Installs a tool like `cowsay` using `uv tool install` and adds its bin directory to the PATH. Includes an example of running the installed tool in a container.

```Dockerfile
ENV PATH=/root/.local/bin:$PATH
RUN uv tool install cowsay
```

```bash
$ docker run -it $(docker build -q .) /bin/bash -c "cowsay -t hello"
```

--------------------------------

### Configure marimo in a non-project environment

Source: https://docs.astral.sh/uv/guides/integration/marimo

Setup a virtual environment and install marimo manually.

```bash
$ uv venv
$ uv pip install numpy
$ uv pip install marimo
$ uv run marimo edit
```

--------------------------------

### Project build system configuration

Source: https://docs.astral.sh/uv/concepts/projects/init

The `pyproject.toml` file defines the project's metadata, dependencies, and build system. This example uses `uv_build` as the build backend, enabling the project to be installed into an environment.

```toml
[project]
name = "example-pkg"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[project.scripts]
example-pkg = "example_pkg:main"

[build-system]
requires = ["uv_build>=0.11.25,<0.12"]
build-backend = "uv_build"

```

--------------------------------

### Install uv with Standalone Installer (Windows)

Source: https://docs.astral.sh/uv

Use this PowerShell command to install uv on Windows systems.

```powershell
PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

```

--------------------------------

### Install dependencies from requirements.txt

Source: https://docs.astral.sh/uv/guides/migration/pip-to-project

Install all packages listed in a requirements.txt file into the current environment.

```bash
$ pip install -r requirements.txt

```

--------------------------------

### Install a Tool with uv

Source: https://docs.astral.sh/uv

Installs a command-line tool, such as `ruff`, using `uv tool install` and verifies its installation.

```shell
$ uv tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
 + ruff==0.5.4
Installed 1 executable: ruff

$ ruff --version
ruff 0.5.4

```

--------------------------------

### Install dependencies from requirements file

Source: https://docs.astral.sh/uv/guides/migration/pip-to-project

Standard command to install dependencies into the current environment.

```bash
$ pip install -r requirements-dev.txt
```

--------------------------------

### Install tool with additional dependencies

Source: https://docs.astral.sh/uv/concepts/tools

Use the `--with` option during tool installation to include additional packages as dependencies. Their executables are not installed by default.

```bash
$ uv tool install --with <extra-package> <tool-package>
```

--------------------------------

### Install uv with WinGet

Source: https://docs.astral.sh/uv/getting-started/installation

Install uv using the WinGet package manager on Windows.

```shell
$ winget install --id=astral-sh.uv  -e

```

--------------------------------

### Install for User

Source: https://docs.astral.sh/uv/reference/cli

Installs packages in the user's site-packages directory.

```bash
--user
```

--------------------------------

### Set up Python using uv python install

Source: https://docs.astral.sh/uv/guides/integration/github

Installs the Python version pinned in the project using the `uv python install` command after uv has been set up. This ensures consistency with project requirements.

```yaml
name: Example

jobs:
  uv-example:
    name: python
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

      - name: Set up Python
        run: uv python install

```

--------------------------------

### Install packages from configuration files

Source: https://docs.astral.sh/uv/pip/packages

Commands for installing dependencies defined in requirements.txt or pyproject.toml files.

```bash
$ uv pip install -r requirements.txt
```

```bash
$ uv pip install -r pyproject.toml
```

```bash
$ uv pip install -r pyproject.toml --extra foo
```

```bash
$ uv pip install -r pyproject.toml --all-extras
```

--------------------------------

### Install uv with Scoop

Source: https://docs.astral.sh/uv/getting-started/installation

Install uv using the Scoop package manager.

```shell
$ scoop install main/uv

```

--------------------------------

### Pass options to the installation script

Source: https://docs.astral.sh/uv/reference/installer

Pass arguments directly to the installation script using the -- separator.

```bash
$ curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --help
```

--------------------------------

### Install from pylock.toml

Source: https://docs.astral.sh/uv/concepts/projects/layout

Install packages into the current environment using a `pylock.toml` file. This ensures reproducible installations by using the exact versions specified in the lockfile.

```bash
uv pip sync pylock.toml
```

```bash
uv pip install -r pylock.toml
```

--------------------------------

### Install missing development library

Source: https://docs.astral.sh/uv/reference/troubleshooting/build-failures

Command to install the necessary development headers for a library.

```bash
$ apt install libgraphviz-dev
```

--------------------------------

### Install a tool

Source: https://docs.astral.sh/uv/guides/tools

Installs a tool into a persistent environment, making its executables available in the PATH.

```bash
$ uv tool install ruff
```

--------------------------------

### Set up Python using setup-python with .python-version

Source: https://docs.astral.sh/uv/guides/integration/github

Uses the official GitHub `setup-python` action to set up Python, respecting the version specified in the `.python-version` file. This can be faster due to GitHub's caching.

```yaml
name: Example

jobs:
  uv-example:
    name: python
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: "Set up Python"
        uses: actions/setup-python@v6
        with:
          python-version-file: ".python-version"

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

```

--------------------------------

### Initialize and Manage a Python Project with uv

Source: https://docs.astral.sh/uv

Demonstrates initializing a new project, adding dependencies, running checks, and locking dependencies using uv.

```shell
$ uv init example
Initialized project `example` at `/home/user/example`

$ cd example

$ uv add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
   Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
 + example==0.1.0 (from file:///home/user/example)
 + ruff==0.5.4

$ uv run ruff check
All checks passed!

$ uv lock
Resolved 2 packages in 0.33ms

$ uv sync
Resolved 2 packages in 0.70ms
Checked 1 package in 0.02ms

```

--------------------------------

### Install Latest Patch Version

Source: https://docs.astral.sh/uv/concepts/python-versions

Install the latest patch version for a given minor version using `uv python install`. For example, `3.12` will install the latest available patch for Python 3.12.

```bash
$ uv python install 3.12

```

--------------------------------

### Docker Example with uv Commands

Source: https://docs.astral.sh/uv/reference/troubleshooting/reproducible-examples

A complete Dockerfile example demonstrating how to initialize a project, add dependencies, sync, and run a Python command using uv. This is suitable for reproducing command-line related issues.

```dockerfile
FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim

RUN uv init /mre
WORKDIR /mre
RUN uv add pydantic
RUN uv sync
RUN uv run -v python -c "import pydantic"

```

--------------------------------

### Enable Bytecode Compilation

Source: https://docs.astral.sh/uv/reference/settings

Compile Python files to bytecode after installation to improve application start times, trading longer installation times for faster startup.

```toml
[tool.uv]
compile-bytecode = true
```

```toml
compile-bytecode = true
```

--------------------------------

### Force Reinstallation of Dependencies

Source: https://docs.astral.sh/uv/concepts/cache

Pass the --reinstall flag to any installation command to force uv to ignore existing installed versions and reinstall them. Example shown with 'uv sync'.

```bash
uv sync --reinstall
```

--------------------------------

### Initialize and Configure a New Project

Source: https://docs.astral.sh/uv/guides/integration/jupyter

Commands to create a new project directory, add ipykernel as a development dependency, and open the project in VS Code.

```bash
$ uv init project

$ cd project

$ uv add --dev ipykernel

$ code .
```

--------------------------------

### Enable bytecode compilation

Source: https://docs.astral.sh/uv/reference/settings

Compiles Python files to bytecode after installation. Trades longer installation times for faster start times, useful for CLI applications and Docker containers.

```toml
[tool.uv.pip]
compile-bytecode = true

```

```ini
[pip]
compile-bytecode = true

```

--------------------------------

### Initialize Bare Project with Additional Options

Source: https://docs.astral.sh/uv/concepts/projects/init

The `--bare` option can be combined with other flags like `--description`, `--author-from`, `--vcs`, and `--python-pin` to further customize the minimal project setup.

```bash
$ uv init example-bare --bare --description "Hello world" --author-from git --vcs git --python-pin

```

--------------------------------

### Initialize a new project with uv init

Source: https://docs.astral.sh/uv/concepts/build-backend

Use the `uv init` command to create a new project that is pre-configured to use the uv build backend.

```bash
$ uv init

```

--------------------------------

### Compile Python bytecode

Source: https://docs.astral.sh/uv/reference/cli

Enable `--compile-bytecode` or `--compile` to compile Python files to bytecode after installation. This can improve application start times at the cost of longer installation times.

```bash
--compile-bytecode
```

--------------------------------

### Include All Optional Dependencies

Source: https://docs.astral.sh/uv/reference/cli

Use the `--all-extras` flag to include all optional dependencies when installing from `pylock.toml`, `pyproject.toml`, `setup.py`, and `setup.cfg` sources.

```bash
--all-extras
```

--------------------------------

### Recognizing a build failure

Source: https://docs.astral.sh/uv/reference/troubleshooting/build-failures

Example output showing a build failure when installing an incompatible version of numpy on Python 3.13.

```text
$ uv pip install -p 3.13 'numpy<1.20'
Resolved 1 package in 62ms
  × Failed to build `numpy==1.19.5`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel()` failed (exit status: 1)

      [stderr]
      Traceback (most recent call last):
        File "<string>", line 8, in <module>
          from setuptools.build_meta import __legacy__ as backend
        File "/home/konsti/.cache/uv/builds-v0/.tmpi4bgKb/lib/python3.13/site-packages/setuptools/__init__.py", line 9, in <module>
          import distutils.core
      ModuleNotFoundError: No module named 'distutils'

      hint: `distutils` was removed from the standard library in Python 3.12. Consider adding a constraint (like `numpy >1.19.5`) to avoid building a version of `numpy` that depends
      on `distutils`.
```

--------------------------------

### Provide Metadata for Git Dependencies

Source: https://docs.astral.sh/uv/concepts/resolution

Example of providing static metadata for a package installed from a Git repository, specifying its version and dependencies.

```toml
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["flash-attn"]

[tool.uv.sources]
flash-attn = { git = "https://github.com/Dao-AILab/flash-attention", tag = "v2.6.3" }

[[tool.uv.dependency-metadata]]
name = "flash-attn"
version = "2.6.3"
requires-dist = ["torch", "einops"]

```

--------------------------------

### Set up Python using setup-python with pyproject.toml

Source: https://docs.astral.sh/uv/guides/integration/github

Uses the official GitHub `setup-python` action to set up Python, specifying `pyproject.toml` to use the latest compatible version based on the project's `requires-python` constraint, ignoring any pin.

```yaml
name: Example

jobs:
  uv-example:
    name: python
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: "Set up Python"
        uses: actions/setup-python@v6
        with:
          python-version-file: "pyproject.toml"

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

```

--------------------------------

### Compile Python bytecode

Source: https://docs.astral.sh/uv/reference/cli

Compiles Python files to bytecode after installation for faster start times. Processes the entire site-packages directory.

```bash
--compile-bytecode
```

```bash
--compile
```

--------------------------------

### Initialize a FastAPI project with uv

Source: https://docs.astral.sh/uv/guides/integration/fastapi

Run this command inside the project directory to create an application layout and a pyproject.toml file.

```bash
$ uv init --app
```

--------------------------------

### Base Docker Image for uv

Source: https://docs.astral.sh/uv/reference/troubleshooting/reproducible-examples

Use this as a starting point for Docker-based reproducible examples. Pin to a specific uv version for consistency.

```dockerfile
FROM ghcr.io/astral-sh/uv:0.5.24-debian-slim

```

--------------------------------

### Running and Testing the Library

Source: https://docs.astral.sh/uv/concepts/projects/init

Demonstrates how to navigate into the library directory and execute its functions using `uv run`.

```bash
cd example-lib
$ uv run python -c "import example_lib; print(example_lib.hello())"
```

--------------------------------

### uv init Command Usage

Source: https://docs.astral.sh/uv/reference/cli

Displays the usage syntax for the 'uv init' command, including available options and arguments.

```bash
uv init [OPTIONS] [PATH]

```

--------------------------------

### Example pyproject.toml with platform-specific dependency

Source: https://docs.astral.sh/uv/concepts/projects/dependencies

This TOML snippet demonstrates how `pyproject.toml` includes an environment marker for a platform-specific dependency, ensuring it's only installed on Linux.

```toml
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["jax; sys_platform == 'linux'"]
```

--------------------------------

### Initialize a packaged application

Source: https://docs.astral.sh/uv/concepts/projects/init

Use the `--package` flag with `uv init` to create a new project intended for packaging and distribution. This sets up a standard package structure.

```bash
$ uv init --package example-pkg

```

--------------------------------

### Add platform-specific dependencies

Source: https://docs.astral.sh/uv/concepts/projects/dependencies

Use environment markers to ensure a dependency is installed only on specific platforms or Python versions. This example adds `jax` only for Linux.

```bash
$ uv add "jax; sys_platform == 'linux'"
```

--------------------------------

### Get System Python Prefix

Source: https://docs.astral.sh/uv/concepts/projects/config

Use this Python command to determine the prefix of your system's Python installation, which can be used to set the UV_PROJECT_ENVIRONMENT variable.

```python
import sysconfig; print(sysconfig.get_config_var('prefix'))
```

--------------------------------

### Example requirements.in

Source: https://docs.astral.sh/uv/pip/compatibility

This file specifies the top-level dependencies for a project. uv will use this to generate a requirements.txt file.

```text
starlette
fastapi

```

--------------------------------

### Install packages into a specified prefix directory

Source: https://docs.astral.sh/uv/reference/settings

Use this to install packages into `lib`, `bin`, and other folders under a specified directory, mimicking a virtual environment. It's generally recommended to use `--python` for alternate environments. Default is None.

```toml
[tool.uv.pip]
prefix = "./prefix"

```

```ini
[pip]
prefix = "./prefix"

```

--------------------------------

### uv tool run with --compile-bytecode Option

Source: https://docs.astral.sh/uv/reference/cli

Enables compilation of Python files to bytecode after installation, which can improve start times for applications like CLIs and Docker containers.

```bash
--compile-bytecode

```

--------------------------------

### Initialize a Library Project

Source: https://docs.astral.sh/uv/concepts/projects/init

Use the `--lib` flag with `uv init` to create a new library project. This implies the `--package` flag, ensuring a packaged project structure.

```bash
$ uv init --lib example-lib
```

--------------------------------

### Initialize an Application Project

Source: https://docs.astral.sh/uv/concepts/projects/init

Use `uv init` to create a new application project in the current directory. This command sets up a basic project structure including `pyproject.toml`, a sample `main.py`, and a README file.

```bash
$ uv init example-app
```

--------------------------------

### Multiple Sources with Different Indexes Based on Platform

Source: https://docs.astral.sh/uv/concepts/projects/dependencies

Use different package indexes for a dependency based on environment markers. This example installs 'torch' from different PyTorch indexes for Darwin and Linux systems.

```toml
[project]
dependencies = ["torch"]

[tool.uv.sources]
torch = [
  { index = "torch-cpu", marker = "platform_system == 'Darwin'"},
  { index = "torch-gpu", marker = "platform_system == 'Linux'"},
]

[[tool.uv.index]]
name = "torch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[[tool.uv.index]]
name = "torch-gpu"
url = "https://download.pytorch.org/whl/cu130"
explicit = true
```

--------------------------------

### Sync Project Dependencies and Run Commands with uv

Source: https://docs.astral.sh/uv/guides/integration/github

Installs project dependencies using `uv sync` and runs commands within the uv-managed environment using `uv run`. This snippet demonstrates a typical workflow after setup.

```yaml
name: Example

jobs:
  uv-example:
    name: python
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

      - name: Install the project
        run: uv sync --locked --all-extras --dev

      - name: Run tests
        # For example, using `pytest`
        run: uv run pytest tests

```

--------------------------------

### Install uv using Installer Script in Docker

Source: https://docs.astral.sh/uv/guides/integration/docker

Installs uv using the official installer script. Requires curl and ca-certificates to be installed first. Ensures the installed binary is on the PATH.

```dockerfile
FROM python:3.12-slim-trixie

# The installer requires curl (and certificates) to download the release archive
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates

# Download the latest installer
ADD https://astral.sh/uv/install.sh /uv-installer.sh

# Run the installer then remove it
RUN sh /uv-installer.sh && rm /uv-installer.sh

# Ensure the installed binary is on the `PATH`
ENV PATH="/root/.local/bin/:$PATH"

```

--------------------------------

### Install a Specific Python Version

Source: https://docs.astral.sh/uv/concepts/python-versions

Install a specific Python version using `uv python install`. uv will verify if the version is installed or install the latest available.

```bash
$ uv python install 3.12.3

```

--------------------------------

### Example Library Project Structure

Source: https://docs.astral.sh/uv/concepts/projects/init

A library project initialized with `--lib` follows a standard `src` layout and includes a `py.typed` marker for type hinting.

```tree
example-lib/
├── .python-version
├── README.md
├── pyproject.toml
└── src
    └── example_lib
        ├── py.typed
        └── __init__.py
```

--------------------------------

### Request tool with extras

Source: https://docs.astral.sh/uv/guides/tools

Use the `--from` option to run a tool with specific extras, optionally combined with version selection.

```bash
$ uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report
```

```bash
$ uvx --from 'mypy[faster-cache,reports]==1.13.0' mypy --xml-report mypy_report
```

--------------------------------

### Install a Specific Python Implementation

Source: https://docs.astral.sh/uv/concepts/python-versions

Install a specific Python implementation, such as PyPy, using `uv python install`. This command supports installing different Python distributions.

```bash
$ uv python install pypy

```

--------------------------------

### Create a virtual environment with uv

Source: https://docs.astral.sh/uv

Initializes a new virtual environment in the current directory.

```bash
$ uv venv
Using CPython 3.12.3
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
```

--------------------------------

### Install a project with uv

Source: https://docs.astral.sh/uv/guides/integration/docker

Install a project and its dependencies in a Dockerfile, separating dependency caching from source code copying for efficiency.

```dockerfile
COPY pyproject.toml .
RUN uv pip install -r pyproject.toml
COPY . .
RUN uv pip install -e .

```

--------------------------------

### Install and run an older version of Ruff

Source: https://docs.astral.sh/uv/concepts/tools

Install a specific older version of a tool using `uv tool install`. Once installed, `uvx` will use this version by default.

```bash
$ uv tool install ruff==0.5.0

```

```bash
$ ruff --version
ruff 0.5.0
$ uvx ruff --version
ruff 0.5.0

```

--------------------------------

### Install Packages with uv pip

Source: https://docs.astral.sh/uv/reference/cli

Install packages using the `uv pip install` command. Specify packages directly, via requirements files, editable installs, or groups.

```bash
uv pip install [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDITABLE>|--group <GROUP>>
```

--------------------------------

### Create and activate a virtual environment

Source: https://docs.astral.sh/uv/guides/migration/pip-to-project

Best practice for project isolation: create a virtual environment, activate it, and then proceed with package installations.

```bash
$ python -m venv
$ source .venv/bin/activate
$ pip ...

```

--------------------------------

### Upgrade Installed Tools

Source: https://docs.astral.sh/uv/reference/cli

Use this command to upgrade installed tools. Version constraints and specific settings from the initial installation are respected. To upgrade beyond original constraints, use 'uv tool install' again.

```bash
uv tool upgrade [OPTIONS] <NAME>...
```

--------------------------------

### Install uv with wget (macOS/Linux)

Source: https://docs.astral.sh/uv/getting-started/installation

Use wget to download and execute the standalone installer script for uv on macOS and Linux if curl is not available.

```shell
$ wget -qO- https://astral.sh/uv/install.sh | sh

```

--------------------------------

### Install uv using pipx

Source: https://docs.astral.sh/uv/getting-started/installation

Install uv into an isolated environment using pipx, which is the recommended method for PyPI installations.

```shell
$ pipx install uv

```

--------------------------------

### Initialize a script with inline metadata

Source: https://docs.astral.sh/uv/guides/scripts

Create a script file configured for inline metadata using uv init.

```bash
$ uv init --script example.py --python 3.12
```

--------------------------------

### Install uv with Standalone Installer (macOS/Linux)

Source: https://docs.astral.sh/uv

Use this command to install uv on macOS and Linux systems via curl.

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

```

--------------------------------

### uv publish Index Configuration Example

Source: https://docs.astral.sh/uv/reference/cli

Example TOML configuration for a 'uv' index, specifying both 'url' and 'publish-url'.

```toml
[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple"
publish-url = "https://upload.pypi.org/legacy/"
```

--------------------------------

### Install uv using pip

Source: https://docs.astral.sh/uv/getting-started/installation

Install uv directly using pip. Note that this method installs uv into the current environment.

```shell
$ pip install uv

```

--------------------------------

### Verify uv Installation

Source: https://docs.astral.sh/uv/getting-started/first-steps

Run the `uv` command to check if uv is installed and display its help menu. This confirms the installation was successful.

```bash
$ uv
An extremely fast Python package manager.

Usage: uv [OPTIONS] <COMMAND>

...
```

--------------------------------

### uv python install command usage

Source: https://docs.astral.sh/uv/reference/cli

Shows the usage for the `uv python install` command, which is used to download and install Python versions.

```bash
uv python install
```

--------------------------------

### uv publish with Index Configuration

Source: https://docs.astral.sh/uv/reference/cli

Example of publishing using a configured index. The 'url' is used for checking existing files, and 'publish-url' is used for uploading.

```bash
uv publish --index pypi
```

```bash
uv publish --publish-url https://upload.pypi.org/legacy/ --check-url https://pypi.org/simple
```

--------------------------------

### Configure Target Directory for Package Installation

Source: https://docs.astral.sh/uv/reference/settings

Specify a directory to install packages into, bypassing the default Python environment. This is useful for isolated installations.

```toml
[tool.uv.pip]
target = "./target"

```

```ini
[pip]
target = "./target"

```