pytest-dev/pytest · error · UsageError

PYTEST_THEME environment variable has an invalid value

Error message

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

What it means

Raised by TerminalWriter._get_pygments_formatter() when the PYTEST_THEME environment variable names a pygments style that does not exist, causing pygments.util.ClassNotFound. pytest wraps this as a UsageError so the user gets an actionable hint listing how to discover valid style names. This fires at code-highlighting time (e.g. when displaying source in tracebacks).

Solutions

1. Run `pygmentize -L styles` to list available styles and pick a valid one.
2. Unset PYTEST_THEME to use the default.
3. Install the pygments style package that provides the missing style.
4. Check for typos in the environment variable value.

Example fix

# before
export PYTEST_THEME=monokai_old
# after
export PYTEST_THEME=monokai

import os, pygments.styles
theme = os.getenv('PYTEST_THEME')
if theme and theme not in pygments.styles.get_all_styles():
    del os.environ['PYTEST_THEME']

def is_valid_theme(name: str) -> bool:
    import pygments.styles
    return name in set(pygments.styles.get_all_styles())

When it happens

Trigger: Setting PYTEST_THEME=monokai_old (typo) or PYTEST_THEME=custom_style that isn't installed; running pytest in an environment where the referenced pygments style plugin was removed.

Common situations: Dotfile or CI config with a stale theme name; upgrading pygments and a style was renamed/removed; copying a theme setting from another tool that uses different style names.

Related errors

• PYTEST_THEME_MODE environment variable has an invalid value
• alias conflicts with existing configuration option
• is already an alias of
• Blocking conftest files using -p is not supported: -p no
• is not a Warning subclass

AI-assisted analysis of pytest-dev/pytest@0d6fbdeffa (2026-08-11). Data as JSON: /api/errors/57d3844728773dd3. Report an issue: GitHub.

Appendix: 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 0d6fbdeffa)