.. _howto: ############### How-to Guides ############### Practical recipes for common tox tasks. Each section answers a specific "How do I...?" question. ***************** Quick reference ***************** Common commands =============== - Each tox subcommand has a 1 (or 2) letter shortcut, e.g. ``tox run`` = ``tox r``, ``tox config`` = ``tox c``. - Run all default environments: ``tox`` (runs everything in :ref:`env_list`). - Run a specific environment: ``tox run -e 3.13``. - Run multiple environments: ``tox run -e lint,3.13`` (sequential, in order). - Run environments in parallel: ``tox parallel -e 3.13,3.12`` (see :ref:`parallel_mode`). - Run all environments matching a label: ``tox run -m test`` (see :ref:`labels`). - Run all environments matching a factor: ``tox run -f django`` (runs all envs containing the ``django`` factor). - Inspect configuration: ``tox config -e 3.13 -k pass_env``. - Force recreation: ``tox run -e 3.13 -r``. Environment variables ===================== - View environment variables: ``tox c -e 3.13 -k set_env pass_env``. - Pass through system environment variables: use :ref:`pass_env`. - Set environment variables: use :ref:`set_env`. - Setup commands: :ref:`commands_pre`. Teardown commands: :ref:`commands_post`. - Change working directory: :ref:`change_dir` (affects install commands too if using relative paths). Logging ======= tox logs command invocations inside ``.tox//log``. Environment variables with names containing sensitive words (``access``, ``api``, ``auth``, ``client``, ``cred``, ``key``, ``passwd``, ``password``, ``private``, ``pwd``, ``secret``, ``token``) are logged with their values redacted to prevent accidental secret leaking in CI/CD environments. .. ------------------------------------------------------------------------------------------ .. Testing & Verification (most common workflows) .. ------------------------------------------------------------------------------------------ ****************** Test with pytest ****************** A typical pytest configuration: .. tab:: TOML .. code-block:: toml env_list = ["3.13", "3.12"] [env_run_base] deps = ["pytest>=8"] commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]] .. tab:: INI .. code-block:: ini [tox] env_list = 3.13, 3.12 [testenv] deps = pytest>=8 commands = pytest {posargs:tests} When running tox in parallel mode, ensure each pytest invocation is fully isolated by setting a unique temporary directory: .. tab:: TOML .. code-block:: toml [env_run_base] commands = [["pytest", "--basetemp={env_tmp_dir}", { replace = "posargs", default = ["tests"], extend = true }]] .. tab:: INI .. code-block:: ini [testenv] commands = pytest --basetemp="{env_tmp_dir}" {posargs:tests} *********************************************** Collect coverage across multiple environments *********************************************** A common pattern is running tests across several Python versions and combining coverage results. Use :ref:`depends` to ensure coverage runs after all test environments: .. tab:: TOML .. code-block:: toml env_list = ["3.13", "3.12", "coverage"] [env_run_base] deps = ["pytest", "coverage[toml]"] commands = [["coverage", "run", "-p", "-m", "pytest", "tests"]] [env.coverage] skip_install = true deps = ["coverage[toml]"] depends = ["3.*"] commands = [ ["coverage", "combine"], ["coverage", "report", "--fail-under=80"], ] .. tab:: INI .. code-block:: ini [tox] env_list = 3.13, 3.12, coverage [testenv] deps = pytest coverage[toml] commands = coverage run -p -m pytest tests [testenv:coverage] skip_install = true deps = coverage[toml] depends = 3.* commands = coverage combine coverage report --fail-under=80 The ``-p`` flag (parallel mode) creates separate ``.coverage.`` files per environment. ``coverage combine`` merges them before generating the report. .. _tox-exec: ********************************** Run a one-off command (tox exec) ********************************** The ``tox exec`` subcommand runs an arbitrary command inside a tox environment without executing the configured ``commands``, ``commands_pre``, or ``commands_post``. It also skips package installation. Pass the command after ``--``: .. code-block:: bash # Open a Python shell inside the "3.13" environment tox exec -e 3.13 -- python # Check installed packages tox exec -e 3.13 -- pip list # Run a script with the environment's Python tox exec -e 3.13 -- python scripts/migrate.py --dry-run The command must be in the environment's ``PATH`` or listed in :ref:`allowlist_externals`. ``tox exec`` is useful for debugging, running one-off scripts, or interactively exploring an environment without modifying your configuration. .. ------------------------------------------------------------------------------------------ .. Configuration (frequently needed) .. ------------------------------------------------------------------------------------------ ********************************* Override configuration defaults ********************************* tox provides several ways to override configuration values without editing the configuration file. **User-level configuration file**: tox reads a user-level config file whose location is shown in ``tox --help``. The location can be changed via the ``TOX_CONFIG_FILE`` environment variable. **Environment variables**: Any tox setting can be set via an environment variable with the ``TOX_`` prefix: .. code-block:: bash # Use wheel packaging TOX_PACKAGE=wheel tox run -e 3.13 **CLI override**: The ``-x`` (or ``--override``) flag overrides any configuration value: .. code-block:: bash # Force editable install for a specific environment tox run -e 3.13 -x "testenv:3.13.package=editable" ********************************** Use labels to group environments ********************************** Labels let you assign tags to environments and run them as a group with ``tox run -m