Cannot set env vars through user config

[samueljsb]

Issue

I want to set an environment variable when I run tox but only locally. I've been trying to user the user config file to do this but cannot get the value to be picked up by tox.

Why?

I use ghostty as a terminal emulator, which sets the TERM variable to xterm-ghostty. mypy does not recognise that and so won't show any color when run through tox unless I set TERM=xterm-256color. I'd like to avoid setting that for everybody else that's using a terminal emulator that doesn't suffer rom this problem and just scope my solution to my own computer.

I'm very willing to believe I'm doing something wrong, but I can't find any guidance for what to do instead. I'd appreciate some help if anyone has a solution.

Environment

Provide at least:

• OS: MacOS 15.6.1 (24G90)

Output of pip freeze of the host Python, where tox is installed

cachetools==6.2.0
chardet==5.2.0
colorama==0.4.6
distlib==0.4.0
filelock==3.19.1
packaging==25.0
platformdirs==4.4.0
pluggy==1.6.0
pyproject-api==1.9.1
tox==4.30.2
virtualenv==20.34.0

Output of running tox

Output of tox -rvv

py313: 106 W remove tox env folder /private/tmp/testtoxlocal/.tox/py313 [tox/tox_env/api.py:359]
py313: 131 I find interpreter for spec PythonSpec(major=3, minor=13, free_threaded=False) [virtualenv/discovery/builtin.py:77]
py313: 132 D got python info of /opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/bin/python3.13 from /Users/sam.searles-bryant/Library/Application Support/virtualenv/py_info/2/546eceab7df7df28208038fd8f02d9cb93d6a51d4299cd1fd396269924976362.json [virtualenv/app_data/via_disk_folder.py:132]
py313: 132 D got python info of /opt/homebrew/opt/python@3.13/bin/python3.13 from /Users/sam.searles-bryant/Library/Application Support/virtualenv/py_info/2/6ca8f35c51bc4625b88aba368e0e3e6b52bd4f043902a68ceae684135a43d0f2.json [virtualenv/app_data/via_disk_folder.py:132]
py313: 133 D filesystem is not case-sensitive [virtualenv/discovery/info.py:20]
py313: 133 I proposed PythonInfo(spec=CPython3.13.7.final.0-64, system=/opt/homebrew/opt/python@3.13/bin/python3.13, exe=/Users/sam.searles-bryant/.local/pipx/venvs/tox/bin/python, platform=darwin, version='3.13.7 (main, Aug 14 2025, 11:12:11) [Clang 17.0.0 (clang-1700.0.13.3)]', encoding_fs_io=utf-8-utf-8) [virtualenv/discovery/builtin.py:84]
py313: 133 D accepted PythonInfo(spec=CPython3.13.7.final.0-64, system=/opt/homebrew/opt/python@3.13/bin/python3.13, exe=/Users/sam.searles-bryant/.local/pipx/venvs/tox/bin/python, platform=darwin, version='3.13.7 (main, Aug 14 2025, 11:12:11) [Clang 17.0.0 (clang-1700.0.13.3)]', encoding_fs_io=utf-8-utf-8) [virtualenv/discovery/builtin.py:86]
py313: 134 D symlink on filesystem does work [virtualenv/info.py:50]
py313: 134 D filesystem is not case-sensitive [virtualenv/info.py:27]
py313: 148 I create virtual environment via CPython3macOsBrew(dest=/private/tmp/testtoxlocal/.tox/py313, clear=False, no_vcs_ignore=False, global=False) [virtualenv/run/session.py:52]
py313: 148 D create folder /private/tmp/testtoxlocal/.tox/py313/bin [virtualenv/util/path/_sync.py:14]
py313: 148 D create folder /private/tmp/testtoxlocal/.tox/py313/lib/python3.13/site-packages [virtualenv/util/path/_sync.py:14]
py313: 148 D write /private/tmp/testtoxlocal/.tox/py313/pyvenv.cfg [virtualenv/create/pyenv_cfg.py:35]
py313: 148 D    home = /opt/homebrew/Cellar/python@3.13/3.13.7/bin [virtualenv/create/pyenv_cfg.py:40]
py313: 148 D    implementation = CPython [virtualenv/create/pyenv_cfg.py:40]
py313: 148 D    version_info = 3.13.7.final.0 [virtualenv/create/pyenv_cfg.py:40]
py313: 148 D    virtualenv = 20.34.0 [virtualenv/create/pyenv_cfg.py:40]
py313: 149 D    include-system-site-packages = false [virtualenv/create/pyenv_cfg.py:40]
py313: 149 D    base-prefix = /opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13 [virtualenv/create/pyenv_cfg.py:40]
py313: 149 D    base-exec-prefix = /opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13 [virtualenv/create/pyenv_cfg.py:40]
py313: 149 D    base-executable = /opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/bin/python3.13 [virtualenv/create/pyenv_cfg.py:40]
py313: 149 D symlink /opt/homebrew/opt/python@3.13/bin/python3.13 to /private/tmp/testtoxlocal/.tox/py313/bin/python [virtualenv/util/path/_sync.py:34]
py313: 149 D create virtualenv import hook file /private/tmp/testtoxlocal/.tox/py313/lib/python3.13/site-packages/_virtualenv.pth [virtualenv/create/via_global_ref/api.py:98]
py313: 149 D create /private/tmp/testtoxlocal/.tox/py313/lib/python3.13/site-packages/_virtualenv.py [virtualenv/create/via_global_ref/api.py:101]
py313: 149 D ============================== target debug ============================== [virtualenv/run/session.py:54]
py313: 150 D debug via /private/tmp/testtoxlocal/.tox/py313/bin/python /Users/sam.searles-bryant/.local/pipx/venvs/tox/lib/python3.13/site-packages/virtualenv/create/debug.py [virtualenv/create/creator.py:215]
py313: 150 D {
  "sys": {
    "executable": "/private/tmp/testtoxlocal/.tox/py313/bin/python",
    "_base_executable": "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/bin/python3.13",
    "prefix": "/private/tmp/testtoxlocal/.tox/py313",
    "base_prefix": "/opt/homebrew/opt/python@3.13/Frameworks/Python.framework/Versions/3.13",
    "real_prefix": null,
    "exec_prefix": "/private/tmp/testtoxlocal/.tox/py313",
    "base_exec_prefix": "/opt/homebrew/opt/python@3.13/Frameworks/Python.framework/Versions/3.13",
    "path": [
      "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python313.zip",
      "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13",
      "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/lib-dynload",
      "/private/tmp/testtoxlocal/.tox/py313/lib/python3.13/site-packages"
    ],
    "meta_path": [
      "<class '_virtualenv._Finder'>",
      "<class '_frozen_importlib.BuiltinImporter'>",
      "<class '_frozen_importlib.FrozenImporter'>",
      "<class '_frozen_importlib_external.PathFinder'>"
    ],
    "fs_encoding": "utf-8",
    "io_encoding": "utf-8"
  },
  "version": "3.13.7 (main, Aug 14 2025, 11:12:11) [Clang 17.0.0 (clang-1700.0.13.3)]",
  "makefile_filename": "/opt/homebrew/opt/python@3.13/Frameworks/Python.framework/Versions/3.13/lib/python3.13/config-3.13-darwin/Makefile",
  "os": "<module 'os' (frozen)>",
  "site": "<module 'site' (frozen)>",
  "datetime": "<module 'datetime' from '/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/datetime.py'>",
  "math": "<module 'math' from '/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/lib-dynload/math.cpython-313-darwin.so'>",
  "json": "<module 'json' from '/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/__init__.py'>"
} [virtualenv/run/session.py:55]
py313: 180 I add seed packages via FromAppData(download=False, pip=bundle, via=copy, app_data_dir=/Users/sam.searles-bryant/Library/Application Support/virtualenv) [virtualenv/run/session.py:59]
py313: 181 D got embed update of distribution pip from /Users/sam.searles-bryant/Library/Application Support/virtualenv/wheel/3.13/embed/3/pip.json [virtualenv/app_data/via_disk_folder.py:132]
py313: 182 D install pip from wheel /Users/sam.searles-bryant/.local/pipx/venvs/tox/lib/python3.13/site-packages/virtualenv/seed/wheels/embed/pip-25.2-py3-none-any.whl via CopyPipInstall [virtualenv/seed/embed/via_app_data/via_app_data.py:51]
py313: 183 D copy directory /Users/sam.searles-bryant/Library/Application Support/virtualenv/wheel/3.13/image/1/CopyPipInstall/pip-25.2-py3-none-any/pip-25.2.dist-info to /private/tmp/testtoxlocal/.tox/py313/lib/python3.13/site-packages/pip-25.2.dist-info [virtualenv/util/path/_sync.py:42]
py313: 191 D copy directory /Users/sam.searles-bryant/Library/Application Support/virtualenv/wheel/3.13/image/1/CopyPipInstall/pip-25.2-py3-none-any/pip to /private/tmp/testtoxlocal/.tox/py313/lib/python3.13/site-packages/pip [virtualenv/util/path/_sync.py:42]
py313: 297 D copy /Users/sam.searles-bryant/Library/Application Support/virtualenv/wheel/3.13/image/1/CopyPipInstall/pip-25.2-py3-none-any/pip-25.2.virtualenv to /private/tmp/testtoxlocal/.tox/py313/lib/python3.13/site-packages/pip-25.2.virtualenv [virtualenv/util/path/_sync.py:42]
py313: 298 D generated console scripts pip3 pip pip3.13 pip-3.13 [virtualenv/seed/embed/via_app_data/pip_install/base.py:45]
py313: 298 I add activators for Bash, CShell, Fish, Nushell, PowerShell, Python [virtualenv/run/session.py:65]
py313: 300 D write /private/tmp/testtoxlocal/.tox/py313/pyvenv.cfg [virtualenv/create/pyenv_cfg.py:35]
py313: 300 D    home = /opt/homebrew/Cellar/python@3.13/3.13.7/bin [virtualenv/create/pyenv_cfg.py:40]
py313: 300 D    implementation = CPython [virtualenv/create/pyenv_cfg.py:40]
py313: 300 D    version_info = 3.13.7.final.0 [virtualenv/create/pyenv_cfg.py:40]
py313: 300 D    virtualenv = 20.34.0 [virtualenv/create/pyenv_cfg.py:40]
py313: 300 D    include-system-site-packages = false [virtualenv/create/pyenv_cfg.py:40]
py313: 300 D    base-prefix = /opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13 [virtualenv/create/pyenv_cfg.py:40]
py313: 300 D    base-exec-prefix = /opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13 [virtualenv/create/pyenv_cfg.py:40]
py313: 300 D    base-executable = /opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/bin/python3.13 [virtualenv/create/pyenv_cfg.py:40]
py313: 301 W commands[0]> python -c 'import os; print(os.getenv("FOOBAR"))' [tox/tox_env/api.py:461]
None
py313: 322 I exit 0 (0.02 seconds) /private/tmp/testtoxlocal> python -c 'import os; print(os.getenv("FOOBAR"))' pid=89172 [tox/execute/api.py:294]
  py313: OK (0.22=setup[0.20]+cmd[0.02] seconds)
  congratulations :) (0.25 seconds)

Minimal example

A toxfile that will show the value of the FOOBAR environment variable:

# tox.ini
[tox]
envlist = py313

[testenv]
commands =
  python -c 'import os; print(os.getenv("FOOBAR"))'

A user config file that tries every way I can think of to set the FOOBAR environment variable:

# user.ini
[tox]
setenv =
  FOOBAR = 1

[testenv]
setenv =
  FOOBAR = 2

[testenv:py]
setenv =
  FOOBAR = 3

[testenv:py313]
setenv =
  FOOBAR = 4

Running tox shows the environment variable is not set:

$ TOX_USER_CONFIG_FILE=user.ini tox
py313: commands[0]> python -c 'import os; print(os.getenv("FOOBAR"))'
None
  py313: OK (0.04=setup[0.02]+cmd[0.03] seconds)
  congratulations :) (0.07 seconds)

[EdVanDance]

I think you're looking for CLI overriding.

tox --override testenv.set_env+=FOOBAR=1

[samueljsb]

My hope was to be able to run tox without needing to type out all that extra stuff every time I use it. The TERM env var is always passed through so I've been using TERM=xterm-256color tox as a workaround, but it's a bit annoying.

Ideally I'd be able to only add the env var for my mypy environments, but I'd settle for having it everywhere.

@EdVanDance are you suggesting that this config key doesn't (and shouldn't) work in user config files? If so, do you know if there's anywhere that can tell me which subset of the configuration is allowed in user files?

[EdVanDance]

Sorry I'm not familiar with user config files, so I can't answer that.

But you can also do overrides via env vars, if you don't want to type them out every time.