### uv pip install example

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Example of installing packages using uv. This demonstrates a basic usage scenario for the uv pip interface.

```bash
uv pip install "requests"
```

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

### Install and Use uv Tools

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/docker/index.md

Install tools using `uv tool install` and ensure the tool bin directory is on the PATH. This example installs `cowsay`.

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

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

### uv troubleshoot example

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Example of running the troubleshoot command. This command helps diagnose and resolve common issues with uv installations or configurations.

```bash
uv troubleshoot
```

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

### Run ty with uvx

Source: https://github.com/astral-sh/docs/blob/main/site/ty/installation/index.md

Quickly start using ty without a formal installation by using uvx.

```bash
uvx ty

```

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

### Install Latest uv with setup-uv Action

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/github/index.md

Installs the latest version of uv using the official GitHub Action. This is a basic setup for any project.

```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

```

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

### uv config get example

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Example of getting a uv configuration value. This command retrieves the current value of a specific configuration setting.

```bash
uv config get python.interpreter
```

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

### Install a Package

Source: https://github.com/astral-sh/docs/blob/main/site/uv/pip/packages/index.md

Use this command to install a package from PyPI. For example, to install Flask.

```bash
$ uv pip install flask
```

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

### Install uv

Source: https://github.com/astral-sh/docs/blob/main/site/ruff/contributing/index.html

Install the `uv` package manager using the provided script. This is a prerequisite for other development setup steps.

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

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

### Download and run ty installer script with curl

Source: https://github.com/astral-sh/docs/blob/main/site/ty/installation/index.md

Use curl to download and execute the standalone ty installation script for a quick setup.

```bash
$ curl -LsSf https://astral.sh/ty/install.sh | sh

```

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

### Reproduce build failure with pip

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/troubleshooting/build-failures/index.html

This example demonstrates how to reproduce a build failure using pip, which helps in determining if the issue is specific to uv or a general problem with the package build process. It involves setting up a virtual environment, activating it, and then attempting to install the problematic package.

```bash
uv venv -p 3.13 --seed
source .venv/bin/activate
pip install --use-pep517 --no-cache --force-reinstall 'numpy==1.19.5'
Collecting numpy==1.19.5
  Using cached numpy-1.19.5.zip (7.3 MB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
ERROR: Exception:
Traceback (most recent call last):
  ... 
  File "/Users/example/.cache/uv/archive-v0/3783IbOdglemN3ieOULx2/lib/python3.13/site-packages/pip/_vendor/pyproject_hooks/_impl.py", line 321, in _call_hook
    raise BackendUnavailable(data.get('traceback', ''))
pip._vendor.pyproject_hooks._impl.BackendUnavailable: Traceback (most recent call last):
  File "/Users/example/.cache/uv/archive-v0/3783IbOdglemN3ieOULx2/lib/python3.13/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 77, in _build_backend
    obj = import_module(mod_path)
  File "/Users/example/.local/share/uv/python/cpython-3.13.0-macos-aarch64-none/lib/python3.13/importlib/__init__.py", line 88, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1310, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 1022, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/private/var/folders/6p/k5sd5z7j31b31pq4lhn0l8d80000gn/T/pip-build-env-vdpjme7d/overlay/lib/python3.13/site-packages/setuptools/__init__.py", line 9, in <module>
    import distutils.core
ModuleNotFoundError: No module named 'distutils'
```

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

### Install Multiple Packages

Source: https://github.com/astral-sh/docs/blob/main/site/uv/pip/packages/index.md

Install several packages simultaneously by listing them after the install command. For instance, installing Flask and Ruff.

```bash
$ uv pip install flask ruff
```

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

### Install a tool from a Git source

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/tools/index.html

Install tools directly from Git repositories using `uv tool install`.

```bash
uv tool install git+https://github.com/httpie/cli
```

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

### Setup Non-Project Marimo Environment

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/marimo/index.md

To run marimo in a virtual environment not associated with a project, create a venv, install dependencies like numpy and marimo, and then start the server.

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

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

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

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/github/index.md

Uses the `actions/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

```

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

### Install uv with setup-uv Action

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/github/index.html

Use the astral-sh/setup-uv action to install uv. This respects the Python version pinned in your project.

```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
```

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

### Initialize a new project with uv build backend

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/build-backend/index.html

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

```bash
$ uv init
```

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

### Full Example: Invariant Generics Setup

Source: https://github.com/astral-sh/docs/blob/main/site/ty/reference/typing-faq/index.md

Provides the complete setup for the invariant generics example, including dataclass definitions for Entry, Directory, and File, and the modify function.

```python
from dataclasses import dataclass

@dataclass
class Entry:
     path: str
     def size_bytes(self) -> int: ...

@dataclass
class Directory(Entry):
    def children(self) -> list[Entry]: ...

@dataclass
class File(Entry):
    def content(self) -> bytes: ...

def modify(entries: list[Entry]):
    entries.append(File("README.txt")) # mutation

directories: list[Directory] = [Directory("Downloads"), Directory("Documents")]
modify(directories)  # ty emits an error on this call
```

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

### Install Pre-commit Hooks

Source: https://github.com/astral-sh/docs/blob/main/site/ruff/contributing/index.html

Install the 'prek' tool and then install the pre-commit hooks to automatically run validation checks before committing.

```bash
uv tool install prek
prek install
```

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

### Install a specific version of a tool

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/tools/index.md

Install a specific version of a tool using `uv tool install`. This example installs Ruff version 0.6.0.

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

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

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

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/github/index.md

Uses the `actions/setup-python` action to set up Python, ignoring project pins and using the latest compatible version based on `pyproject.toml`. This leverages GitHub's caching for speed.

```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

```

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

### Initialize an Application Project

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/projects/init/index.md

Use `uv init` followed by a project name to create a new application project. This is the default behavior.

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

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

### Install Package at Specific Version

Source: https://github.com/astral-sh/docs/blob/main/site/uv/pip/packages/index.md

Install a package to a precise version, for example, Ruff version 0.3.0.

```bash
$ uv pip install 'ruff==0.3.0'
```

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

### uv config list example

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Example of listing all uv configuration values. This command displays all currently active configuration settings and their values.

```bash
uv config list
```

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

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

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/github/index.html

Configure GitHub Actions to use the latest Python version compatible with the project's pyproject.toml file using the actions/setup-python action.

```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
```

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

### Enable Bytecode Compilation After Installation

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/settings/index.md

Set `compile-bytecode` to `true` to compile Python files to bytecode during installation, improving application start times at the cost of longer installation.

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

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

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

### Pass options to uv installation script

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/installer/index.md

Pass arguments directly to the uv installation script, for example, to display help information.

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

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

### Install Ansible with executables from related packages

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/tools/index.md

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

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

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

### Example requirements.in file

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/resolution/index.html

A sample requirements.in file specifying a direct dependency with a version constraint.

```text
flask>=2.0.0
```

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

### Initialize and Compile Requirements

Source: https://github.com/astral-sh/docs/blob/main/site/uv/pip/compile/index.html

This example demonstrates initializing a `requirements.txt` file with a specific version and then compiling it. The generated file includes a comment indicating the command used for compilation.

```bash
echo "ruff==0.3.0" > requirements.txt
echo "ruff" | uv pip compile - -o requirements.txt
# This file was autogenerated by uv via the following command:
#    uv pip compile - -o requirements.txt
ruff==0.3.0
```

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

### uv python list example

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Example of listing all managed Python versions. This command shows which Python interpreters uv has installed and can manage.

```bash
uv python list
```

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

### uv init --build-backend Option

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Initializes a project with a specified build backend, implicitly enabling the --package option. Supports various popular build backends.

```bash
Implicitly sets `--package`.

May also be set with the `UV_INIT_BUILD_BACKEND` environment variable.

Possible values:

- `uv`: Use uv as the project build backend
- `hatch`: Use [hatchling](https://pypi.org/project/hatchling) as the project build backend
- `flit`: Use [flit-core](https://pypi.org/project/flit-core) as the project build backend
- `pdm`: Use [pdm-backend](https://pypi.org/project/pdm-backend) as the project build backend
- `poetry`: Use [poetry-core](https://pypi.org/project/poetry-core) as the project build backend
- `setuptools`: Use [setuptools](https://pypi.org/project/setuptools) as the project build backend
- `maturin`: Use [maturin](https://pypi.org/project/maturin) as the project build backend
- `scikit`: Use [scikit-build-core](https://pypi.org/project/scikit-build-core) as the project build backend
```

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

### uv python executable example

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Example of getting the executable path for a managed Python version. This is useful for direct invocation or integration with other tools.

```bash
uv python executable 3.11
```

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

### Install from Git repository

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/tools/index.html

Use the `--from` option with a Git URL to install and run a tool from a repository.

```bash
uvx --from git+https://github.com/httpie/cli httpie
```

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

### Project structure after uv init and add

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/fastapi/index.html

Illustrates the project directory structure after initializing with uv and adding FastAPI as a dependency.

```text
project
├── pyproject.toml
└── app
    ├── __init__.py
    ├── main.py
    ├── dependencies.py
    ├── routers
    │   ├── __init__.py
    │   ├── items.py
    │   └── users.py
    └── internal
        ├── __init__.py
        └── admin.py
```

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

### Install a tool

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/tools/index.md

Install a tool, making its executables available on the system's PATH. A persistent virtual environment is used.

```bash
uv tool install <tool>
```

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

### View uv Installation Script Options

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/installer/index.html

Pass the `--help` argument to the uv installation script via `sh -s --` to view available command-line options.

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

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

### Seed Environment and Start Jupyter Lab

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/jupyter/index.html

Use `uv venv --seed` to prepare the environment and then `uv run --with jupyter` to start Jupyter Lab. This ensures subsequent `%pip install` commands within the notebook install into the project's virtual environment.

```bash
uv venv --seed

```

```bash
uv run --with jupyter jupyter lab

```

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

### Set up Python using uv python install

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/github/index.md

Sets up the Python environment by running `uv python install`. This command respects the Python version pinned in the project.

```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

```

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

### Include additional dependencies during tool installation

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/tools/index.html

Use the `--with` option with `uv tool install` to include extra packages in the tool's environment upon installation. This ensures all necessary dependencies are present from the start.

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

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

### Incorrect Docstring Start (D404)

Source: https://github.com/astral-sh/docs/blob/main/site/ruff/rules/docstring-starts-with-this/index.html

This example shows a docstring that incorrectly starts with 'This function'. It violates PEP 257's recommendation for imperative mood.

```python
def average(values: list[float]) -> float:
    """This function returns the mean of the given values."""
```

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

### Prefix Installation Guidance

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

The `--prefix` option installs packages into standard directories under a specified location, mimicking a virtual environment. It's generally recommended to use `--python` instead, as `--prefix` installations reference the installing interpreter, potentially causing portability issues.

```bash
In general, prefer the use of `--python` to install into an alternate environment, as scripts and other artifacts installed via `--prefix` will reference the installing interpreter, rather than any interpreter added to the `--prefix` directory, rendering them non-portable.

Unlike other install operations, this command does not require discovery of an existing Python environment and only searches for a Python interpreter to use for package resolution. If a suitable Python interpreter cannot be found, uv will install one. To disable this, add `--no-python-downloads`.
```

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

### Import a package in Python

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/migration/pip-to-project/index.html

Example of importing an installed package into a Python script.

```python
import fastapi
```

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

### Initialize a packaged application

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/projects/init/index.md

Use the `--package` flag with `uv init` to create a project intended for packaging and distribution, such as publishing to PyPI.

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

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

### Compile Bytecode After Installation

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Enable compilation of Python files to bytecode after installation to improve application start times. This option can be set via the UV_COMPILE_BYTECODE environment variable.

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

```bash
--compile
```

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

### uv pip sync example

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Example of syncing dependencies using uv. This is useful for ensuring a project has the exact dependencies specified.

```bash
uv pip sync requirements.txt
```

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

### Enable Bytecode Compilation

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/settings/index.md

Enable compilation of Python files to bytecode after installation. This trades longer installation times for faster start times, useful for CLIs and Docker containers.

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

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

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

### uv tool run with bytecode compilation

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Enables compilation of Python files to bytecode after installation for `uv tool run`. This can improve start times at the cost of longer installation times.

```bash
uv tool run --compile-bytecode
```

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

### uv auth list example

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Example of listing configured authentication credentials. This command shows all registries for which uv has stored authentication information.

```bash
uv auth list
```

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

### Compile bytecode after installation

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.html

Enable bytecode compilation with --compile-bytecode to trade longer installation times for faster application start times. This is particularly useful for CLI applications and Docker containers.

```bash
uv tool upgrade --compile-bytecode
```

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

### uv dependencies list example

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Example of listing all dependencies for a project. This command shows the current dependencies defined in the project's manifest.

```bash
uv dependencies list --pyproject
```

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

### Example Library Project Structure

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/projects/init/index.md

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

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

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

### uv CLI Options: Help

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Displays concise help for the command.

```bash
--help
-h

```

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

### Compile Python Bytecode

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Enables compilation of Python files to bytecode during installation. This can improve application start times at the cost of longer installation times. It processes the entire site-packages directory and ignores errors, similar to pip.

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

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

### Compile Bytecode

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

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. It can also be set via the `UV_COMPILE_BYTECODE` environment variable.

```bash
uv version --compile-bytecode
```

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

### uv init Usage

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

The basic usage of the uv init command, including optional arguments for path.

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

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

### Install uv with PowerShell (Windows)

Source: https://github.com/astral-sh/docs/blob/main/site/uv/getting-started/installation/index.html

Use PowerShell to download and execute the uv installation script. This is the recommended method for Windows. The execution policy may need to be adjusted.

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

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

### uv run --compile-bytecode option

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Enables the compilation of Python files to bytecode (`.pyc`) after installation. This can improve application start times at the cost of longer installation times. It processes the entire site-packages directory and ignores errors during compilation.

```bash
uv run --compile-bytecode
```

```bash
uv run --compile
```

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

### Locked dependencies generated by pip freeze

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/migration/pip-to-project/index.html

An example of a requirements.txt file generated by pip freeze, showing exact versions of installed packages.

```ini
annotated-types==0.7.0
anyio==4.8.0
fastapi==0.115.11
idna==3.10
pydantic==2.10.6
pydantic-core==2.27.2
sniffio==1.3.1
starlette==0.46.1
typing-extensions==4.12.2
```

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

### Import and use os.spawnlp

Source: https://github.com/astral-sh/docs/blob/main/site/ruff/rules/start-process-with-no-shell/index.html

This example demonstrates the usage of `os.spawnlp` which is flagged by this rule. Ensure that `arbitrary_user_input` is validated before being passed to the command.

```python
import os

def insecure_function(arbitrary_user_input: str):
    os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", arbitrary_user_input)
```

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

### Install and Run a Tool in Docker

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/docker/index.html

Install a tool like 'cowsay' in a Docker container and execute it. Ensure the tool's bin directory is on the PATH.

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

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

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

### Run MkDocs Development Server

Source: https://github.com/astral-sh/docs/blob/main/site/ruff/contributing/index.html

Start the MkDocs development server to preview documentation changes locally. This command requires `uvx` to be installed.

```bash
uvx --with-requirements docs/requirements.txt -- mkdocs serve -f mkdocs.yml
```

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

### Class with Google Docstring

Source: https://github.com/astral-sh/docs/blob/main/site/ruff/rules/undocumented-public-class/index.html

This example shows a Python class with a docstring formatted according to the Google style guide, satisfying the D101 rule.

```python
class Player:
    """A player in the game.

    Attributes:
        name (str): The name of the player.
        points (int): The number of points the player has.

    Methods:
        add_points(points: int) -> None:
            Add points to the player's score.
    """
    def __init__(self, name: str, points: int = 0) -> None:
        self.name: str = name
        self.points: int = points

    def add_points(self, points: int) -> None:
        self.points += points
```

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

### Install from Pyproject.toml with All Optional Dependencies

Source: https://github.com/astral-sh/docs/blob/main/site/uv/pip/packages/index.md

Install all optional dependencies defined in the `pyproject.toml` file.

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

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

### Run a tool with extras using --from

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/tools/index.md

Use the `--from` option to run a tool with specific extras. This example runs `mypy` with `faster-cache` and `reports` extras.

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

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

### Class with NumPy Docstring

Source: https://github.com/astral-sh/docs/blob/main/site/ruff/rules/undocumented-public-class/index.html

This example demonstrates a Python class with a docstring formatted according to the NumPy style guide, fulfilling the D101 rule.

```python
class Player:
    """A player in the game.

    Attributes
    ----------
    name : str
        The name of the player.
    points : int
        The number of points the player has.

    Methods
    -------
    add_points(points: int) -> None
        Add points to the player's score.
    """
    def __init__(self, name: str, points: int = 0) -> None:
        self.name: str = name
        self.points: int = points

    def add_points(self, points: int) -> None:
        self.points += points
```

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

### Initialize a bare project with additional options

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/projects/init/index.md

The `--bare` option can be combined with other flags like `--description`, `--author-from`, `--vcs`, and `--python-pin` to selectively enable features while maintaining a minimal project structure.

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

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

### Compile Python bytecode

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.html

Enable `--compile-bytecode` or `--compile` to compile Python files to bytecode after installation. This can improve application start times, especially for CLIs and Docker containers, at the cost of longer installation times. It processes the entire site-packages directory.

```bash
uv sync --compile-bytecode
```

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

### Initialize uv Project for FastAPI

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/fastapi/index.md

Use `uv init --app` to create a project with an application layout and a `pyproject.toml` file for a FastAPI project.

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

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

### Compiling Python Bytecode

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Enable the --compile-bytecode option to compile Python files to bytecode after installation. This can improve application start times by trading longer installation times for faster subsequent imports. This option can also be set using the UV_COMPILE_BYTECODE environment variable.

```bash
By default, uv does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, uv will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the `UV_COMPILE_BYTECODE` environment variable.
```

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

### Default Resolution: Latest Version

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/resolution/index.md

This example shows the default behavior of `uv pip compile` which installs the latest compatible version of a package and its dependencies.

```text
requirements.in

flask>=2.0.0

```

```text
# This file was autogenerated by uv via the following command:
#    uv pip compile requirements.in -o requirements.txt
blinker==1.7.0
    # via flask
click==8.1.7
    # via flask
flask==3.0.0
itsdangerous==2.1.2
    # via flask
jinja2==3.1.2
    # via flask
markupsafe==2.1.3
    # via
    #   jinja2
    #   werkzeug
werkzeug==3.0.1
    # via flask

```

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

### Initialize Project with uv

Source: https://github.com/astral-sh/docs/blob/main/site/ruff/tutorial/index.html

Initializes a new Python project using uv, creating a standard project structure.

```bash
uv init --lib numbers
```

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

### Initializing a Packaged Application

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/projects/init/index.html

Create a new project intended for packaging and distribution, such as for PyPI. This command structures the project with a 'src' directory.

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

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

### Example Lambda Event Payload

Source: https://github.com/astral-sh/docs/blob/main/site/uv/guides/integration/aws-lambda/index.html

A sample JSON payload representing an HTTP GET request to the root path, suitable for testing a Lambda function.

```json
{
  "httpMethod": "GET",
  "path": "/",
  "requestContext": {},
  "version": "1.0"
}
```

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

### Install from Requirements Files

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Use the --requirements option to install packages listed in various supported file formats, including requirements.txt, .py, pylock.toml, pyproject.toml, setup.py, and setup.cfg. Reading from stdin is also supported.

```bash
--requirements requirements.txt

```

```bash
-r requirements.txt

```

```bash
-r -

```

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

### Get System Python Prefix

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/projects/config/index.md

Execute this Python code 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'))
```

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

### Django Model Field Order Violation

Source: https://github.com/astral-sh/docs/blob/main/site/ruff/rules/django-unordered-body-content-in-model/index.html

This example shows a violation of the Django Style Guide where `__str__` is defined before a model field. This order is flagged by the linter.

```python
from django.db import models

class StrBeforeFieldModel(models.Model):
    class Meta:
        verbose_name = "test"
        verbose_name_plural = "tests"

    def __str__(self):
        return "foobar"

    first_name = models.CharField(max_length=32)
    last_name = models.CharField(max_length=40)
```

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

### Initialize a New Library Project

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/projects/init/index.md

Use the `uv init --lib` command to create a new library project. This flag implies `--package`, ensuring the library is packaged for distribution.

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

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

### Install numpy with uv, encountering build failure

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/troubleshooting/build-failures/index.html

This example shows a typical build failure when installing a package like numpy with uv, specifically highlighting the 'ModuleNotFoundError: No module named 'distutils''. It also includes a hint from uv suggesting a version constraint to avoid the issue.

```bash
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`.
```

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

### uv init --app Option

Source: https://github.com/astral-sh/docs/blob/main/site/uv/reference/cli/index.md

Creates a project intended for an application, such as web servers, scripts, or CLIs. This is the default behavior if --lib is not specified.

```bash
This is the default behavior if `--lib` is not requested.

This project kind is for web servers, scripts, and command-line interfaces.

By default, an application is not intended to be built and distributed as a Python package. The `--package` option can be used to create an application that is distributable, e.g., if you want to distribute a command-line interface via PyPI.
```

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

### Select Python Version with py launcher

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/python-versions/index.md

After installation, you can select a specific Python version using the `py` launcher on Windows. This example shows how to select the Astral/CPython3.13.1 version.

```bash
py -V:Astral/CPython3.13.1
```

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

### Install Packages from Requirements File

Source: https://github.com/astral-sh/docs/blob/main/site/uv/pip/packages/index.html

Install multiple packages listed in a `requirements.txt` file using the `-r` flag.

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

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

### Initialize an application project

Source: https://github.com/astral-sh/docs/blob/main/site/uv/concepts/projects/init/index.html

Use `uv init` to create a new project for an application. This command generates a standard project structure including a pyproject.toml, a sample main file, a README, and a Python version pin file.

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

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

### Class Hierarchy Setup for Invariant List Example

Source: https://github.com/astral-sh/docs/blob/main/site/ty/reference/typing-faq/index.html

Defines `Entry`, `Directory`, and `File` classes to demonstrate list invariance. The `Directory` and `File` classes inherit from `Entry`.

```python
from dataclasses import dataclass

@dataclass
class Entry:
    path: str
    def size_bytes(self) -> int: ...

@dataclass
class Directory(Entry):
    def children(self) -> list[Entry]: ...

@dataclass
class File(Entry):
    def content(self) -> bytes: ...
```

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

### Install Ruff with uv

Source: https://github.com/astral-sh/docs/blob/main/site/ruff/installation/index.html

Install Ruff using `uv`. Recommended for managing project dependencies. Add Ruff as a development dependency.

```bash
# Install Ruff globally.
uv tool install ruff@latest

# Or add Ruff to your project.
uv add --dev ruff
```