Skip to content
Back to top
View this page

# tox

## 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: ``)

## Environment variables

TOXENV

> comma separated list of environments (overridable by ‘-e’)