DOKK / manpages / debian 13 / tox / tox.1.en
TOX(1) Project name not set TOX(1)

tox - automation project

tox [subcommand] [options] [args ...]

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.

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.

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} ...


  • -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: [])

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)

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]


  • -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: [])

  • -v, --verbose - increase verbosity (default: 2)
  • -q, --quiet - decrease verbosity (default: 0)

  • -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: )

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]


  • -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: [])

  • -v, --verbose - increase verbosity (default: 2)
  • -q, --quiet - decrease verbosity (default: 0)

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]


  • -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: [])

  • -v, --verbose - increase verbosity (default: 2)
  • -q, --quiet - decrease verbosity (default: 0)

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

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]


•
path (default: venv)

  • -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: [])

  • -v, --verbose - increase verbosity (default: 2)
  • -q, --quiet - decrease verbosity (default: 0)

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]


  • -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: [])

  • -v, --verbose - increase verbosity (default: 2)
  • -q, --quiet - decrease verbosity (default: 0)

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]


  • -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: [])

  • -v, --verbose - increase verbosity (default: 2)
  • -q, --quiet - decrease verbosity (default: 0)

  • -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: )

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]


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

  • -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: [])

  • -v, --verbose - increase verbosity (default: 2)
  • -q, --quiet - decrease verbosity (default: 0)

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]


  • -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: [])

  • -v, --verbose - increase verbosity (default: 2)
  • -q, --quiet - decrease verbosity (default: 0)

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]


  • -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: [])

  • -v, --verbose - increase verbosity (default: 2)
  • -q, --quiet - decrease verbosity (default: 0)

  • -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)

TOXENV

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


tox-dev

March 30, 2025 4.25