### Install Pre-commit Hooks with Extra Setup Commands (INI)

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Use extra_setup_commands to install and run pre-commit hooks after environment setup but before test execution. This is useful for tasks that need to be done during the setup phase.

```ini
[testenv]
deps = pre-commit
extra_setup_commands = pre-commit install-hooks
commands = pre-commit run --all-files
```

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

### Install Pre-commit Hooks with Extra Setup Commands (TOML)

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Use extra_setup_commands to install and run pre-commit hooks after environment setup but before test execution. This is useful for tasks that need to be done during the setup phase.

```toml
[tool.tox.env_run_base]
deps = ["pre-commit"]
extra_setup_commands = [
  ["pre-commit", "install-hooks"],
]
commands = [
  ["pre-commit", "run", "--all-files"],
]
```

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

### Setup man page for virtual environment installs

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/install.rst

Run the 'tox man' command to set up the man page when tox is installed in a virtual environment. This command makes the man page accessible on the system's MANPATH.

```bash
tox man
```

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

### Develop MkDocs Documentation with Tox (TOML)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Set up a Tox environment in TOML to run a local development server for MkDocs. This includes installing MkDocs and its material theme, and starting the server.

```toml
[env.docs]
description = "run a development server for documentation"
deps = [
    "mkdocs>=1.3",
    "mkdocs-material",
]
commands = [
    ["mkdocs", "build", "--clean"],
    ["python", "-c", "print('###### Starting local server. Press Control+C to stop ######')"],
    ["mkdocs", "serve", "-a", "localhost:8080"],
]
```

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

### GitLab CI Integration with uv

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Example GitLab CI configuration to set up uv, install tox with tox-uv, and run tox.

```yaml
# .gitlab-ci.yml
test:
  image: python:3.13
  before_script:
    - curl -LsSf https://astral.sh/uv/install.sh | sh
    - uv tool install tox --with tox-uv
  script:
    - tox run -e 3.13
```

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

### Local Release Example

Source: https://github.com/tox-dev/tox/blob/main/docs/development.rst

Example of executing the local release command with a specific version number.

```shell
tox r -e release -- 4.27.0
```

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

### GitHub Actions CI/CD Integration with uv

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Example GitHub Actions workflow to set up Python and uv, install tox with tox-uv, and run tox environments.

```yaml
# .github/workflows/tests.yml
name: tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.12", "3.13", "3.14"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - uses: astral-sh/setup-uv@v5
      - run: uv tool install tox --with tox-uv
      - run: tox run -e ${{ matrix.python-version }}
```

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

### INI Core Settings Example

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Example of core settings in an INI configuration file for tox.

```ini
[tox]
env_list = 3.13, 3.12, lint
```

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

### TOML Core Settings Example

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Example of core settings in a TOML configuration file for tox.

```toml
env_list = ["3.13", "3.12", "lint"]
```

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

### Install Tox using uv

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/install.rst

Use uv to install the tox tool. This method installs tox in an isolated environment, recommended for easy upgrades.

```bash
# install uv per https://docs.astral.sh/uv/#getting-started
uv tool install tox
tox --help
```

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

### INI Configuration for Legacy and Modern Environments

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Example INI configuration demonstrating the use of 'virtualenv_spec' for a legacy environment and a standard setup for a modern environment.

```ini
[testenv:legacy]
base_python = python3.6
virtualenv_spec = virtualenv<20.22.0
commands = python -c 'import sys; print(sys.version)'

[testenv:modern]
base_python = python3.15
commands = python -c 'import sys; print(sys.version)'
```

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

### Expanded INI Environments Example

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Example output showing environments generated by INI expansion syntax with mixed enumerations and ranges.

```shell
> tox l
default environments:
py38  -> [no description]
py39  -> [no description]
py310 -> [no description]
py311 -> [no description]
py313 -> [no description]
py314 -> [no description]
```

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

### Platform Negation for Dependencies (TOML)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Use negation with platform factors in TOML to conditionally install dependencies on all platforms except specific ones. This example installs 'uvloop' on non-Windows and 'pyinotify' on non-macOS.

```toml
[env_run_base]
deps = [
    { replace = "if", condition = "not factor.win32", then = ["uvloop"], extend = true },
    { replace = "if", condition = "not factor.darwin", then = ["pyinotify"], extend = true },
]
```

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

### INI Environment Base Settings Example

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Example of base environment settings in an INI configuration file for tox.

```ini
[testenv]
description = run the test suite with pytest
deps =
    pytest>=8
commands =
    pytest {posargs:tests}
```

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

### TOML Configuration Inheritance Example

Source: https://github.com/tox-dev/tox/blob/main/docs/explanation.rst

Demonstrates TOML configuration inheritance where environment-specific settings fall back to the base section if not defined.

```toml
[env_run_base]
commands = [["pytest", "tests"]]

[env.test]
description = "run the test suite with pytest"
```

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

### Install Tox using pipx

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/install.rst

Use pipx to install tox. This method installs tox in an isolated environment, recommended for easy upgrades.

```bash
python -m pip install pipx-in-pipx --user
pipx install tox
tox --help
```

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

### User Configuration Example (INI)

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Example of a user-level tox configuration file in INI format. This allows modification of default CLI command values.

```ini
[tox]
skip_missing_interpreters = true
```

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

### Tox configuration example: JSON format

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Example of Tox configuration extracted in JSON format, representing environment settings for 'py'.

```json
{
  "env": {
    "py": {
      "deps": [
        "pytest"
      ],
      "commands": [
        "pytest"
      ]
    }
  }
}
```

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

### Install Tox using pip

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/install.rst

Install tox using pip. This method is discouraged if isolated installation is possible. Be cautious with system-managed Python installations.

```bash
python -m pip install --user tox
python -m tox --help
```

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

### Complete Tox Plugin Logging Example

Source: https://github.com/tox-dev/tox/blob/main/docs/plugin/howto.rst

Demonstrates using both logger.info and logger.warning with the special format for dimmed output within a tox_before_run_commands hook. This example shows how to integrate logging into Tox's execution flow.

```python
import logging

from tox.plugin import impl
from tox.tox_env.api import ToxEnv

logger = logging.getLogger(__name__)


@impl
def tox_before_run_commands(tox_env: ToxEnv) -> None:
    # Visible at -vv or higher
    logger.info("preparing environment %s", tox_env.name)
    # Visible at -v or higher, with dimmed plugin name prefix
    logger.warning(
        "%s%s> %s", "", __package__, f"running pre-checks for {tox_env.name}"
    )
```

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

### Install tox with completion support

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/cli.rst

Install tox with the 'completion' extra to enable shell completion. This is a prerequisite for configuring shell completion.

```bash
uv tool install 'tox[completion]'
```

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

### TOML Environment Base Settings Example

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Example of base environment settings in a TOML configuration file for tox.

```toml
[env_run_base]
description = "run the test suite with pytest"
deps = ["pytest>=8"]
commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]]
```

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

### Install Dependencies with Extras (TOML)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Use the 'extras' setting in tox.toml to install your package with specified optional dependencies for testing or documentation builds.

```toml
# tox.toml
[env_run_base]
extras = ["testing"]

[env.docs]
extras = ["docs"]
commands = [["sphinx-build", "-W", "docs", "docs/_build/html"]]
```

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

### INI Expansion Syntax Example

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Illustrates the use of enumerations and numerical ranges in INI env_list for environment generation.

```ini
[tox]
env_list = py3{8-10, 11, 13-14}

[testenv]
deps =
    py{310,311-314}: urllib3
setenv =
    py{310,311-314}: FOO=bar
```

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

### Install Dependencies with Extras (INI)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Use the 'extras' setting in the INI format for tox configuration to install your package with optional dependencies.

```ini
[testenv]
extras = testing

[testenv:docs]
extras = docs
commands = sphinx-build -W docs docs/_build/html
```

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

### Parallel Execution Example

Source: https://github.com/tox-dev/tox/blob/main/docs/explanation.rst

Demonstrates running multiple Tox environments in parallel with a specified degree of parallelization.

```bash
$ tox -e 3.13,3.12,coverage -p all
✔ OK 3.12 in 9.533 seconds
✔ OK 3.13 in 9.96 seconds
✔ OK coverage in 2.0 seconds
___________________________ summary ______________________________________________________
  3.13: commands succeeded
  3.12: commands succeeded
  coverage: commands succeeded
  congratulations :)
```

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

### Skip only package installation

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Use --skip-pkg-install to skip building and installing the project package, while still allowing dependency installation. Useful for refreshing dependencies without rebuilding the package.

```bash
tox run -e 3.13 --skip-pkg-install
```

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

### Generated Tox Environments Example

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Example output showing the environments generated by a generative environment list configuration.

```shell
> tox l
default environments:
py39-django41-sqlite  -> [no description]
py39-django41-mysql   -> [no description]
py39-django40-sqlite  -> [no description]
py39-django40-mysql   -> [no description]
py310-django41-sqlite -> [no description]
py310-django41-mysql  -> [no description]
py310-django40-sqlite -> [no description]
py310-django40-mysql  -> [no description]
py311-django41-sqlite -> [no description]
py311-django41-mysql  -> [no description]
py311-django40-sqlite -> [no description]
py311-django40-mysql  -> [no description]
```

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

### INI Configuration Inheritance Example

Source: https://github.com/tox-dev/tox/blob/main/docs/explanation.rst

Demonstrates INI configuration inheritance where environment-specific settings fall back to the base section if not defined.

```ini
[testenv]
commands = pytest tests

[testenv:test]
description = run the test suite with pytest
```

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

### TOML Configuration for Dependencies with Constraints

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Example of specifying dependencies and constraint files in TOML format for Tox environments.

```toml
[tool.tox.env_run_base]
deps = [
  "pytest>=8",
  "-r requirements.txt",
  "-c constraints.txt",
]
```

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

### Install Dependencies Without Package (TOML)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Configure tox.toml with 'package = "deps-only"' to install dependencies, including extras, without installing the project package itself. Useful for documentation builds or linting.

```toml
# pyproject.toml
[project]
name = "myproject"
dependencies = ["httpx>=0.27"]

[project.optional-dependencies]
docs = ["sphinx>=7", "furo"]

# tox.toml
[env.docs]
package = "deps-only"
extras = ["docs"]
commands = [["sphinx-build", "-W", "docs", "docs/_build/html"]]
```

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

### TOML Lint Environment Settings Example

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Example of specific lint environment settings in a TOML configuration file for tox.

```toml
[env.lint]
description = "run linters"
skip_install = true
deps = ["ruff"]
commands = [["ruff", "check", "."]]
```

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

### INI Lint Environment Settings Example

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Example of specific lint environment settings in an INI configuration file for tox.

```ini
[testenv:lint]
description = run linters
skip_install = true
deps =
    ruff
commands = ruff check .
```

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

### INI Configuration for Labels

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Example of how to define labels in the tox.ini file for grouping test environments.

```ini
[tox]
labels =
     test = 3.14t, 3.14, 3.13, 3.12
     static = ruff, mypy
```

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

### INI Configuration for Dependencies with Constraints

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Example of specifying dependencies and constraint files in INI format for Tox environments.

```ini
[testenv]
deps =
    pytest>=7,<8
    -r requirements.txt
    -c constraints.txt
```

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

### Tox Summary Report Example

Source: https://github.com/tox-dev/tox/blob/main/docs/explanation.rst

This bash snippet shows an example of the summary report generated by tox, indicating the success or failure of environments.

```bash
____________________ summary ____________________
3.13: commands succeeded
ERROR:   3.12: commands failed
```

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

### TOML Configuration for Legacy and Modern Environments

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Example TOML configuration showing how to specify a 'virtualenv_spec' for a legacy environment and a standard configuration for a modern environment.

```toml
[env.legacy]
base_python = ["python3.6"]
virtualenv_spec = "virtualenv<20.22.0"
commands = [["python", "-c", "import sys; print(sys.version)"]]

[env.modern]
base_python = ["python3.15"]
commands = [["python", "-c", "import sys; print(sys.version)"]]
```

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

### Install latest unreleased Tox using uv

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/install.rst

Install the latest unreleased version of tox from its git repository using uv. This is discouraged and intended for testing purposes.

```bash
uv tool install --from git+https://github.com/tox-dev/tox.git@main tox
```

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

### Fail-Fast Execution Example

Source: https://github.com/tox-dev/tox/blob/main/docs/explanation.rst

Illustrates stopping Tox execution immediately after the first environment failure.

```bash
tox run -e 3.13,3.12,3.11 --fail-fast
```

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

### Install Locked Dependencies with Extras/Groups (INI)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Use 'extras' or 'dependency_groups' in INI-style tox configuration with 'pylock' to select specific PEP 751 lock file entries for installation.

```ini
[testenv:docs]
pylock = pylock.toml
extras = docs

[testenv:dev]
pylock = pylock.toml
dependency_groups = dev
```

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

### Changelog Entry Example

Source: https://github.com/tox-dev/tox/blob/main/docs/development.rst

An example of a bugfix changelog entry using reStructuredText format. It should be concise, in sentence case, and complete the sentence 'This change will...'.

```rst
Instead of raising ``UnicodeDecodeError`` when command output includes non-utf-8 bytes, ``tox`` will now use
``surrogateescape`` error handling to convert the unrecognized bytes to escape sequences according to :pep:`383`
- by :user:`masenf`
```

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

### Install Locked Dependencies (TOML)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Use the 'pylock' setting in tox.toml to install dependencies directly from a PEP 751 lock file (pylock.toml). This ensures pinned requirements are used.

```toml
# tox.toml
[env_run_base]
pylock = "pylock.toml"
```

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

### TOML Configuration for Tox

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Example TOML configuration for tox, defining environments for different Python versions and linting.

```toml
env_list = ["3.13", "3.12", "lint"]

[env_run_base]
description = "run the test suite with pytest"
deps = [
    "pytest>=8",
]
commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]]

[env.lint]
description = "run linters"
skip_install = true
deps = ["ruff"]
commands = [["ruff", "check", { replace = "posargs", default = ["."], extend = true }]]
```

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

### INI Configuration for Tox

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Example INI configuration for tox, defining environments for different Python versions and linting.

```ini
[tox]
env_list = 3.13, 3.12, lint

[testenv]
description = run the test suite with pytest
deps =
    pytest>=8
commands =
    pytest {posargs:tests}

[testenv:lint]
description = run linters
skip_install = true
deps =
    ruff
commands = ruff check {posargs:.}
```

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

### Skip Environment Installation

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Reruns tests without reinstalling dependencies or the package. Useful for offline work or when no changes require reinstallation.

```bash
tox run -e 3.13 --skip-env-install
```

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

### Tox Lifecycle Diagram

Source: https://github.com/tox-dev/tox/blob/main/docs/explanation.rst

This diagram illustrates the sequential flow of the Tox lifecycle, from initial configuration loading through environment setup and execution to final reporting.

```mermaid
flowchart TD
    start(( )) --> config[Load configuration]

    config --> envloop

    subgraph envloop [for each selected environment]
        direction TB
        create[Create environment]
        create --> depmode{pylock set?}
        depmode -- yes --> pylock[Install from pylock.toml]
        depmode -- no --> deps[Install deps + dependency groups]
        pylock --> pkg{package project?}
        deps --> pkg
        pkg -- yes --> build[Build and install package]
        pkg -- no --> extra
        build --> extra[Run extra_setup_commands]
        extra --> cmds
        cmds[Run commands]
    end

    cmds --> report[Report results]
    report --> done(( ))

    classDef configStyle fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f
    classDef envStyle fill:#dcfce7,stroke:#22c55e,stroke-width:2px,color:#14532d
    classDef pkgStyle fill:#ffedd5,stroke:#f97316,stroke-width:2px,color:#7c2d12
    classDef setupStyle fill:#fde68a,stroke:#fbbf24,stroke-width:2px,color:#78350f
    classDef cmdStyle fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#3b0764
    classDef reportStyle fill:#ccfbf1,stroke:#14b8a6,stroke-width:2px,color:#134e4a
    classDef decisionStyle fill:#fef9c3,stroke:#eab308,stroke-width:2px,color:#713f12
    classDef pylockStyle fill:#e0e7ff,stroke:#6366f1,stroke-width:2px,color:#312e81

    class config configStyle
    class create,deps envStyle
    class build pkgStyle
    class extra setupStyle
    class cmds cmdStyle
    class report reportStyle
    class depmode,pkg decisionStyle
    class pylock pylockStyle
```

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

### TOML Reference Command Arguments

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Example of referencing command arguments from another configuration using 'ref' with 'extend=true'. This is useful for integrating command lists.

```toml
[tool.tox.env.a]
package = "skip"
commands = [[{ replace = "ref", env = "a", key = "list_dependencies_command", extend = true }]]
```

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

### Conditional Value with Boolean Logic (AND)

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Combine multiple environment variable conditions using boolean logic (`and`, `or`, `not`). This example sets `DEPLOY_TARGET` only if both `env.CI` and `env.DEPLOY` are true.

```toml
[env.A]
set_env.DEPLOY_TARGET = { replace = "if", condition = "env.CI and env.DEPLOY", then = "production", "else" = "none" }
```

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

### Build Documentation Locally

Source: https://github.com/tox-dev/tox/blob/main/docs/development.rst

Build the project's documentation locally using tox. The built documentation will be available in the .tox/docs_out/html folder.

```shell
tox -e docs
```

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

### Run Tox with Multiple Python Versions in Docker

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Execute Tox commands within a Docker container that has multiple Python versions installed. This example targets Python 3.13, 3.12, and 3.11.

```shell
docker run --rm -v "$(pwd)":/app tox-runner tox run -e 3.13,3.12,3.11
```

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

### Override Configuration via Command Line (INI)

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Examples of overriding INI configuration settings directly from the command line using the --override flag.

```bash
tox --override testenv.ignore_errors=True
```

```bash
tox --override testenv.deps+=pytest-xdist
```

```bash
tox --override testenv.set_env+=baz=quux
```

```bash
tox -x testenv.set_env+=foo=bar -x testenv.set_env+=baz=quux
```

```bash
tox -x testenv.deps+=pytest-xdist -x testenv.deps+=pytest-cov
```

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

### Tox Core Configuration in setup.cfg

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Basic tox configuration using the setup.cfg file format. Similar to tox.ini, it specifies required tox version and environment configurations.

```ini
[tox:tox]
requires =
    tox >= 4.0
env_list =
    3.14t
    3.14
    3.13
    3.12
    type

[testenv]
deps = pytest
commands = pytest tests

[testenv:type]
deps = mypy
commands = mypy src
```

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

### Intercept Package Installations

Source: https://github.com/tox-dev/tox/blob/main/docs/plugin/howto.rst

Run custom logic during package installations using tox_on_install. This hook is triggered whenever tox installs dependencies, the project itself, or other packages.

```python
from typing import Any

from tox.plugin import impl
from tox.tox_env.api import ToxEnv


@impl
def tox_on_install(tox_env: ToxEnv, arguments: Any, section: str, of_type: str) -> None:
    print(f"Installing [{section}] {of_type}: {arguments}")  # noqa: T201
```

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

### Install Dependency Groups in INI

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Define and install dependency groups for a Tox environment using INI format. The `dependency_groups` setting in `[testenv]` specifies which groups to install.

```ini
[testenv]
dependency_groups =
    test
```

```toml
[dependency-groups]
test = [
   "pytest>=8",
]
```

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

### Install Dependency Groups in TOML

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Define and install dependency groups for a Tox environment using TOML format. The `dependency_groups` setting in `tool.tox.env_run_base` specifies which groups to install.

```toml
[dependency-groups]
test = [
   "pytest>=8",
]

[tool.tox.env_run_base]
dependency_groups = [
  "test",
]
```

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

### Verify tox Installation

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Check if tox is installed and accessible in your environment.

```bash
tox --version
```

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

### Install Dependencies Without Package (INI)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Configure INI-style tox files with 'package = deps-only' to install dependencies and extras without installing the project package. This is useful for environments like documentation builds.

```ini
[testenv:docs]
package = deps-only
extras = docs
commands = sphinx-build -W docs docs/_build/html
```

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

### Build Documentation with Sphinx using Tox (TOML)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Configure a Tox environment in TOML format to build documentation using Sphinx. This snippet defines dependencies and the command to run Sphinx.

```toml
[env.docs]
description = "build documentation"
deps = ["sphinx>=7"]
commands = [
    ["sphinx-build", "-d", "{env_tmp_dir}/doctree", "docs", "{work_dir}/docs_out", "--color", "-b", "html"],
    ["python", "-c", "print(f'documentation available under file://{work_dir}/docs_out/index.html')"],
]
```

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

### Add man page to MANPATH for user installs

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/install.rst

Configure the MANPATH environment variable to include the directory where tox installs its man page for user installations. This is typically done in shell configuration files like .bashrc or .zshrc.

```bash
# Add to ~/.bashrc or ~/.zshrc
export MANPATH="$HOME/.local/share/man:$MANPATH"
```

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

### Tox Configuration Migration (TOML)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Example of migrating common tox.ini patterns to the recommended tox.toml format, including core settings, base environment settings, and environment-specific overrides.

```toml
# tox.toml - values at root level are core settings
requires = ["tox>=4.20"]
env_list = ["3.13", "3.12", "lint"]

# base settings for run environments
[env_run_base]
deps = ["pytest>=8"]
commands = [["pytest", "tests"]]

# environment-specific overrides
[env.lint]
skip_install = true
deps = ["ruff"]
commands = [["ruff", "check", "."]]
```

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

### Set Environment Variable from File

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Demonstrates how to set an environment variable using a value from another environment variable, as defined in a configuration file.

```ini
[testenv]
set_env = file|{env:variable}
```

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

### InvocationError Exit Code Example

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Illustrates the format of an InvocationError when a command fails. This example shows a generic exit code of 1.

```shell
ERROR: InvocationError for command
       '<command defined in tox config>' (exited with code 1)
```

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

### Build Documentation with Sphinx using Tox (INI)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Configure a Tox environment in INI format to build documentation using Sphinx. This snippet defines dependencies and the command to run Sphinx.

```ini
[testenv:docs]
description = build documentation
deps =
    sphinx>=7
commands =
    sphinx-build -d "{envtmpdir}{/}doctree" docs "{toxworkdir}{/}docs_out" --color -b html
    python -c 'print(r"documentation available under file://{toxworkdir}{/}docs_out{/}index.html")'
```

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

### Default Fallback Configuration

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Demonstrates how a configuration setting falls back to its default value when no conditional lines match the current environment.

```ini
[testenv]
base_python =
    py312: python3.12
    py313: python3.13
```

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

### Develop MkDocs Documentation with Tox (INI)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Configure a Tox environment in INI format to run a local development server for MkDocs. This snippet includes dependencies and commands for building and serving the documentation.

```ini
[testenv:docs]
description = Run a development server for working on documentation
deps =
    mkdocs>=1.3
    mkdocs-material
commands =
    mkdocs build --clean
    python -c 'print("###### Starting local server. Press Control+C to stop server ######")'
    mkdocs serve -a localhost:8080
```

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

### Specify Build Backend and Dependencies (TOML)

Source: https://github.com/tox-dev/tox/blob/main/docs/explanation.rst

Define package build dependencies and the build backend using a pyproject.toml file. This example uses hatchling for building.

```toml
[build-system]
build-backend = "hatchling.build"
requires = ["hatchling>=0.22", "hatch-vcs>=0.2"]
```

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

### Build and Run Tox in Docker

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Build a Docker image with Tox installed and then run Tox commands against your mounted project directory. This is useful for creating consistent CI environments.

```shell
docker build -t tox-runner .
docker run --rm -v "$(pwd)":/app tox-runner tox run -e 3.13
```

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

### Conditional Dependencies Using Negative Factors

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Install dependencies conditionally based on the absence of a factor. '!lint: pytest' installs pytest for all environments except those with the 'lint' factor.

```ini
[testenv]
deps =
    !lint: pytest
    !lint: coverage
    lint: ruff
```

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

### Install Locked Dependencies with Extras/Groups (TOML)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Specify 'extras' or 'dependency_groups' in tox.toml when using 'pylock' to select specific PEP 751 lock file entries for installation.

```toml
[env.docs]
pylock = "pylock.toml"
extras = ["docs"]

[env.dev]
pylock = "pylock.toml"
dependency_groups = ["dev"]
```

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

### Tox Configuration Migration (INI)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Example of common tox.ini patterns for basic structure, including global settings, default test environment, and specific environment configurations.

```ini
[tox]
requires = tox>=4.20
env_list = 3.13, 3.12, lint

[testenv]
deps = pytest>=8
commands = pytest tests

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

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

### Install latest unreleased Tox using pipx

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/install.rst

Install the latest unreleased version of tox from its git repository using pipx. This is discouraged and intended for testing purposes.

```bash
pipx install git+https://github.com/tox-dev/tox.git@main
```

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

### Run All Default Tox Environments

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Executes all environments listed in the :ref:`env_list` configuration.

```bash
tox
```

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

### List Available Tox Environments

Source: https://github.com/tox-dev/tox/blob/main/docs/tutorial/getting-started.rst

Displays all configured environments along with their descriptions. Helps in understanding the available test matrices.

```bash
tox list
```

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

### Run Development Environment

Source: https://github.com/tox-dev/tox/blob/main/docs/development.rst

Generate the development tox environment and invoke tox from the .tox/dev folder.

```shell
tox -e dev
.tox/dev/bin/tox  # on Linux
.tox/dev/Scripts/tox  # on Windows
```

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

### Install Locked Dependencies (INI)

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Use the 'pylock' setting in INI-style tox configuration to install dependencies from a PEP 751 lock file (pylock.toml), ensuring pinned requirements.

```ini
[testenv]
pylock = pylock.toml
```

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

### TOML Environment Configuration Reference (raw type)

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Demonstrates referencing configuration as raw data using the 'ref' replacement with 'of'. Substitutions are executed in the current environment's scope.

```toml
[env.src]
extras = ["A", "{env_name}"]
[env.dest]
extras = [{ replace = "ref", of = ["env", "src", "extras"], extend = true }, "B"]
```

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

### Install optional dependency groups (extras) in TOML

Source: https://github.com/tox-dev/tox/blob/main/docs/how-to/usage.rst

Specify optional dependency groups (extras) to be installed in a tox environment using the `extras` configuration in TOML. This is defined in your `pyproject.toml`.

```toml
# pyproject.toml
[tool.tox.env]
extras = ["dev", "test"]
```

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

### Subcommand Dispatch Example

Source: https://github.com/tox-dev/tox/blob/main/docs/onboarding.rst

This snippet shows how a subcommand handler is retrieved from parsed options and invoked with the current state. It's used after provisioning to execute the chosen command.

```python
handler = state._options.cmd_handlers[state.conf.options.command]
return handler(state)
```

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

### Conditional Dependencies Based on Environment Name

Source: https://github.com/tox-dev/tox/blob/main/docs/reference/config.rst

Conditionally install dependencies based on specific environment names. 'py310,py39: pytest' installs pytest only for environments named 'py310' or 'py39'.

```ini
[testenv]
deps =
   pip
   format: black
   py310,py39: pytest
```