### Docker usage with tox-uv-bare

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Example Dockerfile demonstrating the installation of uv, tox, and tox-uv-bare. This setup is suitable for containerized environments where uv is pre-installed.

```dockerfile
FROM python:3.12
RUN pip install uv tox tox-uv-bare
# uv is already in the container, no need to bundle it again
```

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

### Install tox-uv with Bundled uv

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Install the recommended tox-uv package which includes a bundled uv binary for immediate use. Validate the installation by checking the tox version.

```bash
uv tool install tox --with tox-uv

tox --version
# Output: tox 4.x.x from ... with uv==0.x.x

tox r -e py312

tox --runner virtualenv r -e py312
```

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

### Configure uv sync flags with multiple options

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Use `uv_sync_flags` to pass additional flags to uv sync. This example shows how to install in non-editable mode and keep extra packages installed.

```ini
uv_sync_flags = --no-editable, --inexact
```

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

### Install tox-uv-bare in Docker

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Use tox-uv-bare in Docker or Kubernetes environments to avoid bundling uv twice, assuming uv is already installed on the system.

```dockerfile
FROM python:3.12
RUN pip install uv tox tox-uv-bare
```

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

### Install tox-uv and use uv

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Install tox-uv using uv to replace the default tox installation. Validate the tox version and then run tox commands, noting that 'tox r -e py312' will use uv, while 'tox --runner virtualenv r -e py312' will use virtualenv and pip.

```bash
uv tool install tox --with tox-uv # use uv to install
tox --version # validate you are using the installed tox
tox r -e py312 # will use uv
tox --runner virtualenv r -e py312 # will use virtualenv+pip
```

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

### Install external packages with --installpkg

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Use the --installpkg flag with 'tox run' to install a specified wheel or tar.gz file into the lock-runner environment after running 'uv sync --no-install-project'.

```bash
# Build a wheel elsewhere and inject it into the lock-runner environment
tox run -e test --installpkg dist/mypackage-1.0.0-py3-none-any.whl

# With sdist
tox run -e test --installpkg dist/mypackage-1.0.0.tar.gz
# Internally runs:
#   uv sync --locked --no-install-project -p <python>
#   uv pip install --reinstall --no-deps mypackage@dist/mypackage-1.0.0.tar.gz
```

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

### Configure package installation mode in tox.ini

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Control how the project's source tree is installed using the 'package' setting. Options include 'skip', 'wheel', 'editable', 'uv', and 'uv-editable', affecting behavior for uv-venv-runner and uv-venv-lock-runner.

```toml
# tox.toml
[env_run_base]
runner = "uv-venv-lock-runner"
package = "wheel"          # install non-editable wheel via uv sync

[env.dev]
runner = "uv-venv-lock-runner"
package = "editable"       # default: editable install

[env.lint]
runner = "uv-venv-lock-runner"
package = "skip"           # don't install the project at all
dependency_groups = ["lint"]
commands = [["ruff", "check", "src/"]]

[env.uv-sources]
runner = "uv-venv-runner"
package = "uv"             # use uv directly (supports tool.uv.sources)
commands = [["python", "-m", "pytest", "tests"]]
```

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

### Python Code Example

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

A simple Python script demonstrating the use of the requests library to fetch JSON data from an HTTP endpoint. This can be used as a target script for tox environments.

```python
import requests
from rich import print

print(requests.get("https://httpbin.org/get").json())
```

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

### Full tox.toml Example for tox-uv

Source: https://context7.com/tox-dev/tox-uv/llms.txt

This is a complete configuration file demonstrating various tox-uv features for a multi-environment project. It includes settings for requires, environment lists, skipping missing interpreters, base environment configurations, and specific environment configurations for linting, type checking, documentation building, and development.

```toml
# tox.toml
requires = ["tox>=4.34.1", "tox-uv>=1.23"]
env_list = ["3.14", "3.13", "3.12", "fix", "type", "docs"]
skip_missing_interpreters = true

[env_run_base]
description = "Run tests under {env_name}"
package = "wheel"
dependency_groups = ["test"]
pass_env = ["CI", "PYTEST_*"]
commands = [["python", "-m", "pytest", "tests", {replace = "posargs", default = [], extend = true}]]

[env.fix]
description = "Lint and format"
skip_install = true
deps = ["pre-commit-uv>=4.2"]
commands = [["pre-commit", "run", "--all-files", "--show-diff-on-failure"]]

[env.type]
description = "Type checking"
runner = "uv-venv-lock-runner"
dependency_groups = ["type"]
commands = [["mypy", "src"]]

[env.docs]
runner = "uv-venv-lock-runner"
extras = ["docs"]
package = "editable"
commands = [["sphinx-build", "docs", "docs/_build/html"]]

[env.dev]
description = "Development environment"
runner = "uv-venv-lock-runner"
package = "editable"
dependency_groups = ["dev"]
no_default_groups = false
commands = [
    ["uv", "pip", "tree"],
    ["python", "-c", "import sys; print(sys.executable)"],
]

```

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

### Basic PEP 723 Runner Configuration

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Configure a tox test environment to use the virtualenv-pep-723 runner, which is backed by uv when installed. This runner transparently uses uv for dependency resolution and installation.

```ini
[testenv:check]
runner = virtualenv-pep-723
script = tools/check.py
```

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

### Run Environments with Standard uv Runner

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Execute tox environments using the default uv-venv-runner. This command creates the virtual environment with uv and installs dependencies using uv pip install.

```bash
tox r -e py312   # creates .tox/py312 venv with uv, installs deps with uv pip install
tox r            # runs all environments in env_list
```

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

### PEP 723 inline script metadata example

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Example of a Python script with PEP 723 inline script metadata. The script declares its required Python version and dependencies within comment blocks.

```python
# /// script
# requires-python = ">=3.12"
# dependencies = ["requests>=2.31", "rich"]

```

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

### Enable system site packages in tox.ini

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Configure a tox test environment to inherit globally installed packages by setting 'system_site_packages' to true. This respects the VIRTUALENV_SYSTEM_SITE_PACKAGES environment variable as a default.

```ini
# tox.ini
[testenv:with-system-pkgs]
system_site_packages = true
package = skip
commands = python -c "import numpy; print(numpy.__version__)"
```

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

### Standard uv Runner Configuration

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Configure tox environments to use the default uv-venv-runner, which replaces virtualenv and pip with uv for environment creation and dependency installation. No explicit runner configuration is needed as it's the default.

```ini
# tox.ini — standard uv runner (this is the default, no explicit runner= needed)
[tox]
env_list = py312, py311, lint

[testenv]
description = run tests with pytest
package = wheel           # build a wheel via PEP-517 and install it
deps =
    pytest>=8
    pytest-cov
commands =
    pytest {posargs:tests}

[testenv:lint]
skip_install = true
deps = ruff
commands = ruff check src/
```

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

### Set TOX_UV_PATH environment variable

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Demonstrates how to set the TOX_UV_PATH environment variable to explicitly specify the location of the uv binary. This is useful for testing custom uv builds or when uv is installed in a non-standard location.

```bash
export TOX_UV_PATH=/custom/path/to/uv
tox r
```

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

### PEP 723 Inline Script Example

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Example of a Python script using PEP 723 inline metadata to declare its Python version and dependencies. This script can be run directly by tox-uv's PEP 723 runner.

```python
# tools/check.py — PEP 723 inline metadata
# /// script
# requires-python = ">=3.12"
# dependencies = ["requests>=2.31", "rich"]
# ///

import requests
from rich import print

print(requests.get("https://httpbin.org/get").json())
```

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

### Tox Development Environment with UV Lock and Extras

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Configure a 'dev' tox environment using uv-venv-lock-runner. It installs dependencies with specified extras ('dev', 'test', 'type') via 'uv sync' from the uv.lock file.

```ini
[testenv:dev]
runner = uv-venv-lock-runner
description = dev environment
extras =
    dev
    test
    type
commands =
    uv pip tree
```

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

### Tox Environment for Code Formatting

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Configure a tox environment named 'fix' to run code formatters and linters using pre-commit-uv. Dependencies are managed by uv, and installation is skipped as it's a pre-commit hook.

```ini
[testenv:fix]
description = run code formatter and linter (auto-fix)
skip_install = true
deps =
    pre-commit-uv>=4.1.1
commands =
    pre-commit run --all-files --show-diff-on-failure
```

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

### Tox Environment for Type Checking with uv.lock

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Set up a tox environment 'type' to use the uv-venv-lock-runner for type checking with mypy. Dependencies are installed using 'uv sync' based on the uv.lock file.

```ini
[testenv:type]
runner = uv-venv-lock-runner
description = run type checker via mypy
commands =
    mypy {posargs:src}
```

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

### Seed Virtual Environments with uv

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Configure Tox to seed virtual environments with pip, setuptools, and wheel using `uv_seed = true`. This is required for legacy editable installs or projects not supporting the pyproject.toml build model.

```ini
# tox.ini
[testenv:legacy]
uv_seed = true
package = skip
deps = my-legacy-package
commands = python -c "import pip; print(pip.__version__)"
```

```bash
# uv venv --seed is passed: pip/setuptools/wheel available in .tox/legacy/
tox r -e legacy
```

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

### Configure Dependency Resolution Strategy with uv

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Set the dependency resolution strategy using `uv_resolution`. Options are `highest` (default), `lowest`, and `lowest-direct`. This flag is passed to `uv pip install` or `uv sync`.

```ini
# tox.ini
[testenv:test-lowest]
description = validate lower-bound dependencies
uv_resolution = lowest
deps =
    pytest
    requests
commands = pytest tests/

[testenv:test-lowest-direct]
description = lowest direct deps, latest transitive
uv_resolution = lowest-direct
deps =
    pytest
    requests
commands = pytest tests/
```

```bash
tox r -e test-lowest        # installs lowest compatible versions of all deps
tox r -e test-lowest-direct # lowest for direct deps only
```

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

### Configure uv sync flags for frozen installations

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

If `--frozen` is included in `uv_sync_flags`, tox-uv will automatically suppress the implicit `--locked` argument as they are mutually exclusive in uv.

```ini
uv_sync_flags = --frozen
```

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

### Explicit UV Runner Configuration

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Explicitly set the runner to uv-venv-pep-723 to ensure uv is used, even if the tox-uv plugin is not installed. This guarantees uv's performance benefits for PEP 723 environments.

```ini
[testenv:check]
runner = uv-venv-pep-723
script = tools/check.py
```

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

### Run Environments with Lock File Runner

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Execute tox environments configured with uv-venv-lock-runner. These commands use 'uv sync --locked' for reproducible installs. An option to skip uv sync is also provided.

```bash
tox r -e type       # runs: uv sync --locked -p <python> then mypy src
tox r -e dev        # runs: uv sync --locked --extra dev --extra test --extra type -p <python>
tox r --skip-uv-sync -e type  # skip uv sync entirely (use existing venv as-is)
```

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

### Configure uv sync flags in tox.ini

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Set custom flags for uv sync operations within a tox environment. Use --no-editable for non-editable installs and --inexact for specific version matching.

```ini
[testenv:upgrade-test]
runner = uv-venv-lock-runner
no_default_groups = false
uv_sync_locked = false
uv_sync_flags = --upgrade
commands = python -m pytest tests/
```

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

### PEP 723 Inline Script Runner Configuration

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Configure a tox environment to use the uv-venv-pep-723 runner for scripts with PEP 723 inline metadata. Alternatively, tox's built-in alias can be used, which is transparently backed by uv when tox-uv is installed.

```ini
# tox.ini
[testenv:check]
runner = uv-venv-pep-723
# or use the tox built-in alias (transparently backed by uv when tox-uv is installed):
```

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

### Lock File Runner Configuration (tox.ini)

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Configure tox environments to use the uv-venv-lock-runner for fully reproducible builds based on a uv.lock file. Dependencies are sourced exclusively from the lockfile, ignoring the 'deps' key.

```ini
# tox.ini
[testenv:type]
runner = uv-venv-lock-runner
description = run mypy
commands = mypy {posargs:src}

[testenv:dev]
runner = uv-venv-lock-runner
description = dev environment with extras
extras =
    dev
    test
    type
commands = python -c "import sys; print(sys.executable)"
```

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

### Configure package root for monorepos

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Specify the location of 'pyproject.toml' and 'uv.lock' relative to 'tox_root' using 'package_root' for monorepo layouts where the package is in a subdirectory.

```ini
# tox.ini — package lives in src/ subdirectory
[testenv]
runner = uv-venv-lock-runner
package_root = src
commands = python -m pytest tests/
```

```bash
# Internally runs: uv sync --directory src --locked -p <python>
tox r
```

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

### Run Tox Scripts with uv

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Execute Tox environments that run specific scripts. Arguments can be forwarded to the script using '--'.

```bash
tox r -e check             # runs tools/check.py with its inline dependencies
tox r -e check -- --verbose  # positional args forwarded to the script
```

```bash
# Disable automatic uv promotion for pep-723 environments:
TOX_UV_NO_PEP723=1 tox r -e check
```

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

### Lock File Runner Configuration (tox.toml)

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Equivalent TOML syntax for configuring the uv-venv-lock-runner, specifying dependency groups and commands for reproducible environments.

```toml
# tox.toml — equivalent TOML syntax
[env_run_base]
runner = "uv-venv-lock-runner"
dependency_groups = ["test"]
commands = [["python", "-m", "pytest", "tests"]]
```

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

### Running Tox with Arguments

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Execute tox commands and forward positional arguments to the underlying script. This allows for flexible control over test execution and verbosity.

```bash
tox r -e check -- --verbose
```

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

### Control uv-venv-lock-runner Dependencies

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Configure `extras`, `dependency_groups`, and `only_groups` for `uv-venv-lock-runner` to control which parts of the `uv.lock` file are synchronized. `no_default_groups` suppresses default dev groups and is automatically true when `dependency_groups` is non-empty.

```toml
# tox.toml
[env.test]
runner = "uv-venv-lock-runner"
dependency_groups = ["test", "type"]   # project + test + type groups
commands = [["python", "-m", "pytest", "tests"]]

[env.docs]
runner = "uv-venv-lock-runner"
extras = ["docs"]                       # project[docs] extras
commands = [["sphinx-build", "docs", "docs/_build"]]

[env.ci-tools]
runner = "uv-venv-lock-runner"
only_groups = ["ci"]                   # ONLY ci group, no project install
no_default_groups = true
commands = [["my-ci-tool", "--check"]]

[env.dev]
runner = "uv-venv-lock-runner"
no_default_groups = false              # include default dev groups
extras = ["dev", "test"]
commands = [["uv", "pip", "tree"]]
```

```bash
tox r -e test      # uv sync --locked --no-default-groups --group test --group type
tox r -e ci-tools  # uv sync --locked --only-group ci
```

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

### Skip uv sync step with --skip-uv-sync flag

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Use the --skip-uv-sync flag with 'tox run' or 'tox exec' to bypass the uv sync step in uv-venv-lock-runner environments. This is useful for CI jobs that reuse cached virtual environments.

```bash
# Create or reuse the venv but skip re-syncing from uv.lock
tox run --skip-uv-sync -e test

# Works with exec too
tox exec --skip-uv-sync -e test -- python -c "import sys; print(sys.version)"
```

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

### Control uv sync locked behavior

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Set `uv_sync_locked` to `false` to avoid conflicts with arguments like `--prerelease` or `--upgrade` when `uv sync` is called with `--locked` by default.

```bash
UV_FROZEN=1 tox
```

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

### Fine-grained uv sync Control

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Use `uv_sync_flags` to pass arbitrary flags to `uv sync` and `uv_sync_locked` (default `true`) to control the `--locked` flag. Setting `uv_sync_locked` to `false` allows flags like `--prerelease` or `--upgrade`. `--frozen` in `uv_sync_flags` or `UV_FROZEN=1` suppresses `--locked`.

```ini
# tox.ini
[testenv:sync-inexact]
runner = uv-venv-lock-runner
no_default_groups = false

```

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

### Configure Python Interpreter Selection with uv

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Control how uv selects Python interpreters using `uv_python_preference`. Valid values include `none`, `only-managed`, `managed`, `system`, `only-system`. The default is `system`. This setting is overridden by `UV_NO_MANAGED_PYTHON` or `UV_MANAGED_PYTHON` environment variables.

```ini
# tox.ini
[testenv]
# Use only managed (uv-downloaded) interpreters — never system Python
uv_python_preference = only-managed
package = skip
commands = python --version

[testenv:ci-strict]
# system: prefer system Python, download only if missing (default)
uv_python_preference = system
package = skip
commands = python --version
```

```toml
# tox.toml — conditional preference using tox factor syntax
[testenv]
uv_python_preference = """
    onlymanaged: only-managed
"""
```

```bash
# Override globally via environment variable
UV_PYTHON_PREFERENCE=only-managed tox r
```

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

### Disabling Automatic UV Promotion

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

To revert to tox's default virtualenv and pip implementation, set the environment variable TOX_UV_NO_PEP723 to 1. This is useful for debugging or when uv integration is not desired.

```bash
TOX_UV_NO_PEP723=1
```

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

### Skip lockfile validation with UV_FROZEN

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Use the UV_FROZEN environment variable to skip lockfile validation, which is useful when the lock was built on a different platform. This can also be set explicitly in the tox.ini configuration.

```bash
# Use --frozen to skip lockfile validation (useful when lock was built on a different platform)
UV_FROZEN=1 tox r -e test

# Explicit --frozen in config (mutually exclusive with --locked, suppressed automatically)
# uv_sync_flags = --frozen
```

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

### Overriding Default Commands in Tox

Source: https://github.com/tox-dev/tox-uv/blob/main/README.md

Customize the commands executed within a tox environment by setting the 'commands' option. This is useful for specifying specific test runners or build processes.

```ini
[testenv:check]
runner = virtualenv-pep-723
script = tools/check.py
commands = python -m pytest tests/
```

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

### Invalidate uv cache with UV_* environment variables

Source: https://context7.com/tox-dev/tox-uv/llms.txt

Changing specific UV_* environment variables set via 'set_env' in tox.ini triggers a full package reinstall by invalidating the uv cache. This ensures uv re-resolves packages under the new settings.

```ini
# tox.ini
[testenv:test-private-index]
package = skip
set_env =
    UV_INDEX_URL = https://private.registry.example.com/simple/
    UV_EXTRA_INDEX_URL = https://pypi.org/simple/
deps = my-private-package>=1.0
commands = python -c "import my_private_package"
# Changing UV_INDEX_URL triggers a cache invalidation and reinstall
```

```ini
# tox.ini — test with pre-release packages
[testenv:test-pre]
package = skip
set_env =
    UV_PRERELEASE = allow
deps = some-package>=2.0a1
commands = python -c "import some_package; print(some_package.__version__)"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.