---
name: "tox"
section: "1"
platform: "linux"
package: "tox"
version: "4.25.0-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/tox"
---

# tox(1)

automation project

## NAME

tox - automation project

## SYNOPSIS

**tox** \[*subcommand*\] \[*options*\] \[*args* ...\]

## DESCRIPTION

tox is a generic virtual environment management and test command line tool you can use for:

- •

  checking your package builds and installs correctly under different environments (such as different Python implementations, versions or installation dependencies),

- •

  running your tests in each of the environments with the test tool of choice,

- •

  acting as a frontend to continuous integration servers, greatly reducing boilerplate and merging CI and shell-based testing.

## OVERVIEW

tox has several subcommands, each with their own options. Below you can find an exhaustive list of options for each of those subcommands.

Each tox subcommand has a 1 (or 2) letter shortcut form too. For example, *tox* *run* can also be written as *tox r* or *tox config* can be shortened to *tox* *c*.

## OPTIONS

### tox entry point

```
tox [-h] [--colored {yes,no}]
    [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
    [-v | -q] [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
    [--runner {virtualenv}] [--version] [--no-provision [REQ_JSON]] [--no-recreate-provision]
    [-r] [-x OVERRIDE]
    {run,r,run-parallel,p,depends,de,list,l,devenv,d,schema,config,c,quickstart,q,exec,e,legacy,le} ...
```

### tox options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--version* - show program's and plugins version number and exit

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox verbosity

every -v increases, every -q decreases verbosity level, default WARNING, map 0=CRITICAL\|1=ERROR\|2=WARNING\|3=INFO\|4=DEBUG\|5=NOTSET

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox run (r)

run environments

```
tox run [-h] [--colored {yes,no}]
        [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
        [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
        [--runner {virtualenv}] [-v | -q] [--result-json path] [--hashseed SEED]
        [--discover path [path ...]] [--list-dependencies | --no-list-dependencies] [-e ENV |
        -m label [label ...] | -f factor [factor ...] | --skip-env re] [-s [v]] [-n] [-b]
        [--installpkg INSTALL_PKG] [--develop] [--no-recreate-pkg] [--skip-pkg-install]
        [--version] [--no-provision [REQ_JSON]] [--no-recreate-provision] [-r] [-x OVERRIDE]
```

### tox run options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--result-json* **PATH** - write a JSON file with detailed information about all commands and results involved (default: **None**)

- •

  *--hashseed* **SEED** - set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range \[1, 4294967295\] (\[1, 1024\] on Windows). Passing **'notset'** suppresses this behavior. (default: **0**)

- •

  *--discover* **PATH** - for Python discovery first try these Python executables (default: **\[\]**)

- •

  *--list-dependencies* - list the dependencies installed during environment setup

- •

  *--no-list-dependencies* - never list the dependencies installed during environment setup

- •

  *-s* **V**, *--skip-missing-interpreters* **V** - don't fail tests for missing interpreters: **{config,true,false}** choice (default: **config**)

- •

  *-n*, *--notest* - do not run the test commands

- •

  *-b*, *--pkg-only*, *--sdistonly* - only perform the packaging activity

- •

  *--installpkg* **INSTALL\_PKG** - use specified package for installation into venv, instead of packaging the project (default: **None**)

- •

  *--develop* - install package in development mode

- •

  *--no-recreate-pkg* - if recreate is set do not recreate packaging tox environment(s)

- •

  *--skip-pkg-install* - skip package installation for this run

- •

  *--version* - show program's and plugins version number and exit

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox run verbosity

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox run select target environment(s)

- •

  *-e* **ENV** - enumerate (ALL -\> all environments, not set -\> use \<env\_list\> from config) (default: **\<env\_list\>**)

- •

  *-m* **LABEL** - labels to evaluate (default: **\[\]**)

- •

  *-f* **FACTOR** - factors to evaluate (passing multiple factors means **'AND'**, passing this option multiple times means **'OR'**) (default: **\[\]**)

- •

  *--skip-env* **RE** - exclude all environments selected that match this regular expression (default: )

### tox run-parallel (p)

run environments in parallel

```
tox run-parallel [-h] [--colored {yes,no}]
                 [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
                 [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
                 [--runner {virtualenv}] [-v | -q] [--result-json path] [--hashseed SEED]
                 [--discover path [path ...]] [--list-dependencies | --no-list-dependencies]
                 [-e ENV | -m label [label ...] | -f factor [factor ...] | --skip-env re]
                 [-s [v]] [-n] [-b] [--installpkg INSTALL_PKG] [--develop]
                 [--no-recreate-pkg] [--skip-pkg-install] [-p VAL] [-o]
                 [--parallel-no-spinner] [--version] [--no-provision [REQ_JSON]]
                 [--no-recreate-provision] [-r] [-x OVERRIDE]
```

### tox run-parallel options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--result-json* **PATH** - write a JSON file with detailed information about all commands and results involved (default: **None**)

- •

  *--hashseed* **SEED** - set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range \[1, 4294967295\] (\[1, 1024\] on Windows). Passing **'notset'** suppresses this behavior. (default: **0**)

- •

  *--discover* **PATH** - for Python discovery first try these Python executables (default: **\[\]**)

- •

  *--list-dependencies* - list the dependencies installed during environment setup

- •

  *--no-list-dependencies* - never list the dependencies installed during environment setup

- •

  *-s* **V**, *--skip-missing-interpreters* **V** - don't fail tests for missing interpreters: **{config,true,false}** choice (default: **config**)

- •

  *-n*, *--notest* - do not run the test commands

- •

  *-b*, *--pkg-only*, *--sdistonly* - only perform the packaging activity

- •

  *--installpkg* **INSTALL\_PKG** - use specified package for installation into venv, instead of packaging the project (default: **None**)

- •

  *--develop* - install package in development mode

- •

  *--no-recreate-pkg* - if recreate is set do not recreate packaging tox environment(s)

- •

  *--skip-pkg-install* - skip package installation for this run

- •

  *-p* **VAL**, *--parallel* **VAL** - run tox environments in parallel, the argument controls limit: all, auto - cpu count, some positive number, zero is turn off (default: **auto**)

- •

  *-o*, *--parallel-live* - connect to stdout while running environments

- •

  *--parallel-no-spinner* - run tox environments in parallel, but don't show the spinner, implies --parallel. Disabled by default if CI is detected (not in legacy API).

- •

  *--version* - show program's and plugins version number and exit

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox run-parallel verbosity

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox run-parallel select target environment(s)

- •

  *-e* **ENV** - enumerate (ALL -\> all environments, not set -\> use \<env\_list\> from config) (default: **\<env\_list\>**)

- •

  *-m* **LABEL** - labels to evaluate (default: **\[\]**)

- •

  *-f* **FACTOR** - factors to evaluate (passing multiple factors means **'AND'**, passing this option multiple times means **'OR'**) (default: **\[\]**)

- •

  *--skip-env* **RE** - exclude all environments selected that match this regular expression (default: )

### tox depends (de)

visualize tox environment dependencies

```
tox depends [-h] [--colored {yes,no}]
            [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
            [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
            [--runner {virtualenv}] [-v | -q] [--result-json path] [--hashseed SEED]
            [--discover path [path ...]] [--list-dependencies | --no-list-dependencies]
            [--version] [--no-provision [REQ_JSON]] [--no-recreate-provision] [-r]
            [-x OVERRIDE]
```

### tox depends options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--result-json* **PATH** - write a JSON file with detailed information about all commands and results involved (default: **None**)

- •

  *--hashseed* **SEED** - set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range \[1, 4294967295\] (\[1, 1024\] on Windows). Passing **'notset'** suppresses this behavior. (default: **0**)

- •

  *--discover* **PATH** - for Python discovery first try these Python executables (default: **\[\]**)

- •

  *--list-dependencies* - list the dependencies installed during environment setup

- •

  *--no-list-dependencies* - never list the dependencies installed during environment setup

- •

  *--version* - show program's and plugins version number and exit

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox depends verbosity

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox list (l)

list environments

```
tox list [-h] [--colored {yes,no}]
         [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
         [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
         [--runner {virtualenv}] [-v | -q] [--result-json path] [--hashseed SEED]
         [--discover path [path ...]] [--list-dependencies | --no-list-dependencies]
         [--no-desc] [-m label [label ...] | -f factor [factor ...] | --skip-env re | -d]
         [--version] [--no-provision [REQ_JSON]] [--no-recreate-provision] [-r] [-x OVERRIDE]
```

### tox list options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--result-json* **PATH** - write a JSON file with detailed information about all commands and results involved (default: **None**)

- •

  *--hashseed* **SEED** - set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range \[1, 4294967295\] (\[1, 1024\] on Windows). Passing **'notset'** suppresses this behavior. (default: **0**)

- •

  *--discover* **PATH** - for Python discovery first try these Python executables (default: **\[\]**)

- •

  *--list-dependencies* - list the dependencies installed during environment setup

- •

  *--no-list-dependencies* - never list the dependencies installed during environment setup

- •

  *--no-desc* - do not show description

- •

  *--version* - show program's and plugins version number and exit

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox list verbosity

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox list select target environment(s)

- •

  *-m* **LABEL** - labels to evaluate (default: **\[\]**)

- •

  *-f* **FACTOR** - factors to evaluate (passing multiple factors means **'AND'**, passing this option multiple times means **'OR'**) (default: **\[\]**)

- •

  *--skip-env* **RE** - exclude all environments selected that match this regular expression (default: )

- •

  *-d* - list just default envs

### tox devenv (d)

sets up a development environment at ENVDIR based on the tox configuration specified

```
tox devenv [-h] [--colored {yes,no}]
           [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
           [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
           [--runner {virtualenv}] [-v | -q] [--result-json path] [--hashseed SEED]
           [--discover path [path ...]] [--list-dependencies | --no-list-dependencies]
           [-e ENV] [--skip-env re] [--no-recreate-pkg] [--version]
           [--no-provision [REQ_JSON]] [--no-recreate-provision] [-r] [-x OVERRIDE]
           [path]
```

### tox devenv positional arguments

- •

  *path* (default: **venv**)

### tox devenv options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--result-json* **PATH** - write a JSON file with detailed information about all commands and results involved (default: **None**)

- •

  *--hashseed* **SEED** - set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range \[1, 4294967295\] (\[1, 1024\] on Windows). Passing **'notset'** suppresses this behavior. (default: **0**)

- •

  *--discover* **PATH** - for Python discovery first try these Python executables (default: **\[\]**)

- •

  *--list-dependencies* - list the dependencies installed during environment setup

- •

  *--no-list-dependencies* - never list the dependencies installed during environment setup

- •

  *-e* **ENV** - environment to run (default: **py**)

- •

  *--skip-env* **RE** - exclude all environments selected that match this regular expression (default: )

- •

  *--no-recreate-pkg* - if recreate is set do not recreate packaging tox environment(s)

- •

  *--version* - show program's and plugins version number and exit

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox devenv verbosity

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox schema

Generate schema for tox configuration

```
tox schema [-h] [--colored {yes,no}]
           [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
           [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
           [--runner {virtualenv}] [-v | -q] [--result-json path] [--hashseed SEED]
           [--discover path [path ...]] [--list-dependencies | --no-list-dependencies]
           [--strict] [--version] [--no-provision [REQ_JSON]] [--no-recreate-provision] [-r]
           [-x OVERRIDE]
```

### tox schema options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--result-json* **PATH** - write a JSON file with detailed information about all commands and results involved (default: **None**)

- •

  *--hashseed* **SEED** - set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range \[1, 4294967295\] (\[1, 1024\] on Windows). Passing **'notset'** suppresses this behavior. (default: **0**)

- •

  *--discover* **PATH** - for Python discovery first try these Python executables (default: **\[\]**)

- •

  *--list-dependencies* - list the dependencies installed during environment setup

- •

  *--no-list-dependencies* - never list the dependencies installed during environment setup

- •

  *--strict* - Disallow extra properties in configuration

- •

  *--version* - show program's and plugins version number and exit

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox schema verbosity

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox config (c)

show tox configuration

```
tox config [-h] [--colored {yes,no}]
           [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
           [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
           [--runner {virtualenv}] [-v | -q] [--result-json path] [--hashseed SEED]
           [--discover path [path ...]] [--list-dependencies | --no-list-dependencies]
           [-k key [key ...]] [--core] [-e ENV | -m label [label ...] |
           -f factor [factor ...] | --skip-env re] [-s [v]] [--develop] [--no-recreate-pkg]
           [--version] [--no-provision [REQ_JSON]] [--no-recreate-provision] [-r]
           [-x OVERRIDE]
```

### tox config options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--result-json* **PATH** - write a JSON file with detailed information about all commands and results involved (default: **None**)

- •

  *--hashseed* **SEED** - set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range \[1, 4294967295\] (\[1, 1024\] on Windows). Passing **'notset'** suppresses this behavior. (default: **0**)

- •

  *--discover* **PATH** - for Python discovery first try these Python executables (default: **\[\]**)

- •

  *--list-dependencies* - list the dependencies installed during environment setup

- •

  *--no-list-dependencies* - never list the dependencies installed during environment setup

- •

  *-k* **KEY** - list just configuration keys specified (default: **\[\]**)

- •

  *--core* - show core options (by default is hidden unless -e ALL is passed)

- •

  *-s* **V**, *--skip-missing-interpreters* **V** - don't fail tests for missing interpreters: **{config,true,false}** choice (default: **config**)

- •

  *--develop* - install package in development mode

- •

  *--no-recreate-pkg* - if recreate is set do not recreate packaging tox environment(s)

- •

  *--version* - show program's and plugins version number and exit

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox config verbosity

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox config select target environment(s)

- •

  *-e* **ENV** - enumerate (ALL -\> all environments, not set -\> use \<env\_list\> from config) (default: **\<env\_list\>**)

- •

  *-m* **LABEL** - labels to evaluate (default: **\[\]**)

- •

  *-f* **FACTOR** - factors to evaluate (passing multiple factors means **'AND'**, passing this option multiple times means **'OR'**) (default: **\[\]**)

- •

  *--skip-env* **RE** - exclude all environments selected that match this regular expression (default: )

### tox quickstart (q)

Command line script to quickly create a tox config file for a Python project

```
tox quickstart [-h] [--colored {yes,no}]
               [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
               [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
               [--runner {virtualenv}] [-v | -q] [--result-json path] [--hashseed SEED]
               [--discover path [path ...]] [--list-dependencies | --no-list-dependencies]
               [--version] [--no-provision [REQ_JSON]] [--no-recreate-provision] [-r]
               [-x OVERRIDE]
               [root]
```

### tox quickstart positional arguments

- •

  *root* - folder to create the tox.ini file (default: **{cwd}**)

### tox quickstart options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--result-json* **PATH** - write a JSON file with detailed information about all commands and results involved (default: **None**)

- •

  *--hashseed* **SEED** - set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range \[1, 4294967295\] (\[1, 1024\] on Windows). Passing **'notset'** suppresses this behavior. (default: **0**)

- •

  *--discover* **PATH** - for Python discovery first try these Python executables (default: **\[\]**)

- •

  *--list-dependencies* - list the dependencies installed during environment setup

- •

  *--no-list-dependencies* - never list the dependencies installed during environment setup

- •

  *--version* - show program's and plugins version number and exit

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox quickstart verbosity

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox exec (e)

execute an arbitrary command within a tox environment

```
tox exec [-h] [--colored {yes,no}]
         [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
         [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
         [--runner {virtualenv}] [-v | -q] [--result-json path] [--hashseed SEED]
         [--discover path [path ...]] [--list-dependencies | --no-list-dependencies] [-e ENV]
         [--skip-env re] [-s [v]] [-n] [-b] [--installpkg INSTALL_PKG] [--develop]
         [--no-recreate-pkg] [--skip-pkg-install] [--version] [--no-provision [REQ_JSON]]
         [--no-recreate-provision] [-r] [-x OVERRIDE]
```

### tox exec options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--result-json* **PATH** - write a JSON file with detailed information about all commands and results involved (default: **None**)

- •

  *--hashseed* **SEED** - set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range \[1, 4294967295\] (\[1, 1024\] on Windows). Passing **'notset'** suppresses this behavior. (default: **0**)

- •

  *--discover* **PATH** - for Python discovery first try these Python executables (default: **\[\]**)

- •

  *--list-dependencies* - list the dependencies installed during environment setup

- •

  *--no-list-dependencies* - never list the dependencies installed during environment setup

- •

  *-e* **ENV** - environment to run (default: **py**)

- •

  *--skip-env* **RE** - exclude all environments selected that match this regular expression (default: )

- •

  *-s* **V**, *--skip-missing-interpreters* **V** - don't fail tests for missing interpreters: **{config,true,false}** choice (default: **config**)

- •

  *-n*, *--notest* - do not run the test commands

- •

  *-b*, *--pkg-only*, *--sdistonly* - only perform the packaging activity

- •

  *--installpkg* **INSTALL\_PKG** - use specified package for installation into venv, instead of packaging the project (default: **None**)

- •

  *--develop* - install package in development mode

- •

  *--no-recreate-pkg* - if recreate is set do not recreate packaging tox environment(s)

- •

  *--skip-pkg-install* - skip package installation for this run

- •

  *--version* - show program's and plugins version number and exit

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox exec verbosity

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox legacy (le)

legacy entry-point command

```
tox legacy [-h] [--colored {yes,no}]
           [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
           [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
           [--runner {virtualenv}] [--version] [-v | -q] [--result-json path]
           [--hashseed SEED] [--discover path [path ...]] [--list-dependencies |
           --no-list-dependencies] [--help-ini] [--showconfig] [-a] [-l] [--devenv ENVDIR]
           [-e ENV | -m label [label ...] | -f factor [factor ...] | --skip-env re] [-s [v]]
           [-n] [-b] [--installpkg INSTALL_PKG] [--develop] [--no-recreate-pkg]
           [--skip-pkg-install] [-p [VAL]] [-o] [--parallel-no-spinner] [--pre]
           [--force-dep req] [--sitepackages] [--alwayscopy] [--no-provision [REQ_JSON]]
           [--no-recreate-provision] [-r] [-x OVERRIDE]
```

### tox legacy options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--colored* **COLORED** - should output be enriched with colors, default is yes unless TERM=dumb or NO\_COLOR is defined.

- •

  *--stderr-color* **STDERR\_COLOR** - color for stderr output, use RESET for terminal defaults. (default: **RED**)

- •

  *--exit-and-dump-after* **SECONDS** - dump tox threads after n seconds and exit the app - useful to debug when tox hangs, 0 means disabled (default: **0**)

- •

  *-c* **FILE**, *--conf* **FILE** - configuration file/folder for tox (if not specified will discover one) (default: **None**)

- •

  *--workdir* **DIR** - tox working directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--root* **DIR** - project root directory (if not specified will be the folder of the config file) (default: **None**)

- •

  *--runner* **DEFAULT\_RUNNER** - the tox run engine to use when not explicitly stated in tox env configuration (default: **virtualenv**)

- •

  *--version* - show program's and plugins version number and exit

- •

  *--result-json* **PATH** - write a JSON file with detailed information about all commands and results involved (default: **None**)

- •

  *--hashseed* **SEED** - set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range \[1, 4294967295\] (\[1, 1024\] on Windows). Passing **'notset'** suppresses this behavior. (default: **0**)

- •

  *--discover* **PATH** - for Python discovery first try these Python executables (default: **\[\]**)

- •

  *--list-dependencies* - list the dependencies installed during environment setup

- •

  *--no-list-dependencies* - never list the dependencies installed during environment setup

- •

  *--help-ini*, *--hi* - show live configuration

- •

  *--showconfig* - show live configuration (by default all env, with -l only default targets, specific via TOXENV/-e)

- •

  *-a*, *--listenvs-all* - show list of all defined environments (with description if verbose)

- •

  *-l*, *--listenvs* - show list of test environments (with description if verbose)

- •

  *--devenv* **ENVDIR** - sets up a development environment at ENVDIR based on the env's tox configuration specified by\`-e\` (-e defaults to py)

- •

  *-s* **V**, *--skip-missing-interpreters* **V** - don't fail tests for missing interpreters: **{config,true,false}** choice (default: **config**)

- •

  *-n*, *--notest* - do not run the test commands

- •

  *-b*, *--pkg-only*, *--sdistonly* - only perform the packaging activity

- •

  *--installpkg* **INSTALL\_PKG** - use specified package for installation into venv, instead of packaging the project (default: **None**)

- •

  *--develop* - install package in development mode

- •

  *--no-recreate-pkg* - if recreate is set do not recreate packaging tox environment(s)

- •

  *--skip-pkg-install* - skip package installation for this run

- •

  *-p* **VAL**, *--parallel* **VAL** - run tox environments in parallel, the argument controls limit: all, auto - cpu count, some positive number, zero is turn off (default: **0**)

- •

  *-o*, *--parallel-live* - connect to stdout while running environments

- •

  *--parallel-no-spinner* - run tox environments in parallel, but don't show the spinner, implies --parallel. Disabled by default if CI is detected (not in legacy API).

- •

  *--pre* - deprecated use PIP\_PRE in set\_env instead - install pre-releases and development versions ofdependencies; this will set PIP\_PRE=1 environment variable

- •

  *--force-dep* **REQ** - Forces a certain version of one of the dependencies when configuring the virtual environment. REQ Examples **'pytest\<6.1'** or **'django\>=2.2'**. (default: **\[\]**)

- •

  *--sitepackages* - deprecated use VIRTUALENV\_SYSTEM\_SITE\_PACKAGES=1, override sitepackages setting to True in all envs

- •

  *--alwayscopy* - deprecated use VIRTUALENV\_ALWAYS\_COPY=1, override always copy setting to True in all envs

- •

  *--no-provision* **REQ\_JSON** - do not perform provision, but fail and if a path was provided write provision metadata as JSON to it (default: **False**)

- •

  *--no-recreate-provision* - if recreate is set do not recreate provision tox environment

- •

  *-r*, *--recreate* - recreate the tox environments

- •

  *-x* **OVERRIDE**, *--override* **OVERRIDE** - configuration override(s), e.g., -x testenv:pypy3.ignore\_errors=True (default: **\[\]**)

### tox legacy verbosity

- •

  *-v*, *--verbose* - increase verbosity (default: **2**)

- •

  *-q*, *--quiet* - decrease verbosity (default: **0**)

### tox legacy select target environment(s)

- •

  *-e* **ENV** - enumerate (ALL -\> all environments, not set -\> use \<env\_list\> from config) (default: **\<env\_list\>**)

- •

  *-m* **LABEL** - labels to evaluate (default: **\[\]**)

- •

  *-f* **FACTOR** - factors to evaluate (passing multiple factors means **'AND'**, passing this option multiple times means **'OR'**) (default: **\[\]**)

- •

  *--skip-env* **RE** - exclude all environments selected that match this regular expression (default: )

config file '/dev/null' active (changed via env var TOX\_USER\_CONFIG\_FILE)

## ENVIRONMENT VARIABLES

TOXENV

comma separated list of environments (overridable by '-e')

## COPYRIGHT

tox-dev