pytest-dev/pytest · error · UsageError

PYTEST_THEME environment variable has an invalid value: '{th

Error message

PYTEST_THEME environment variable has an invalid value: '{theme}'. Hint: See available pygments styles with `pygmentize -L styles`.

What it means

Pytest highlights code in tracebacks using the pygments library. The style is controlled by the PYTEST_THEME environment variable. If the value does not match any registered pygments style name, pygments raises ClassNotFound, which pytest wraps as a UsageError at config time. This prevents the terminal formatter from being constructed with a nonexistent style.

Source

Thrown at src/_pytest/_io/terminalwriter.py:225

    def _get_pygments_lexer(self, lexer: Literal["python", "diff"]) -> Lexer:
        if lexer == "python":
            return PythonLexer()
        elif lexer == "diff":
            return DiffLexer()
        else:
            assert_never(lexer)

    def _get_pygments_formatter(self) -> TerminalFormatter:
        from _pytest.config.exceptions import UsageError

        theme = os.getenv("PYTEST_THEME")
        theme_mode = os.getenv("PYTEST_THEME_MODE", "dark")

        try:
            return TerminalFormatter(bg=theme_mode, style=theme)
        except pygments.util.ClassNotFound as e:
            raise UsageError(
                f"PYTEST_THEME environment variable has an invalid value: '{theme}'. "
                "Hint: See available pygments styles with `pygmentize -L styles`."
            ) from e
        except pygments.util.OptionError as e:
            raise UsageError(
                f"PYTEST_THEME_MODE environment variable has an invalid value: '{theme_mode}'. "
                "The allowed values are 'dark' (default) and 'light'."
            ) from e

    def _highlight(
        self, source: str, lexer: Literal["diff", "python"] = "python"
    ) -> str:
        """Highlight the given source if we have markup support."""
        if not source or not self.hasmarkup or not self.code_highlight:
            return source

        pygments_lexer = self._get_pygments_lexer(lexer)
        pygments_formatter = self._get_pygments_formatter()

View on GitHub (pinned to 98b357f69e)

Solutions

1. Run `pygmentize -L styles` to list valid style names, then set PYTEST_THEME to one of them.
2. Unset PYTEST_THEME entirely to fall back to the pygments default style.
3. Check for typos and case sensitivity in the current PYTEST_THEME value.

Example fix

# before
export PYTEST_THEME=monokaix  # typo

# after
export PYTEST_THEME=monokai
# verify with: pygmentize -L styles

import os
from pygments.styles import get_style_by_name

theme = os.getenv('PYTEST_THEME')
if theme:
    try:
        get_style_by_name(theme)
    except Exception:
        raise ValueError(f"PYTEST_THEME='{theme}' is not a valid pygments style. Run: pygmentize -L styles")

When it happens

Trigger: Setting PYTEST_THEME to a typo or invented name (e.g., PYTEST_THEME=monokaix) before running pytest. The error fires inside _get_pygments_formatter() when TerminalFormatter(bg=theme_mode, style=theme) is constructed and pygments cannot resolve the style name.

Common situations: CI pipelines or shell profiles that export PYTEST_THEME with a value copied from an outdated blog post, a value valid on a different pygments version, or a simple typo. Also occurs when the style is removed or renamed across pygments upgrades.

Related errors

• PYTEST_THEME_MODE environment variable has an invalid value:
• {optname} must be a filename, given: {path}
• {optname} must be a directory, given: {path}
• plugin {name} cannot be disabled
• Blocking conftest files using -p is not supported: -p no:{na

AI-assisted analysis of pytest-dev/pytest@98b357f69e (2026-08-04). Data as JSON: /data/errors/57d3844728773dd3.json. Report an issue: GitHub.