sphinx-doc / sphinx-doc/sphinx

Mismatch between --no-color and NO_COLOR behavior in Sphinx 9.1.0 on Windows

Open
#14,565 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

There appears to be a behavior mismatch between the command-line flag --no-color and the NO_COLOR environment variable:

  1. --no-color still outputs ANSI control sequences (not colorized text, but cursor/line control sequences like \x1b[2K) on my Windows setup.
  2. NO_COLOR=1 does not output these sequences.

Consequence: Users trying to disable terminal formatting get different behavior depending on which mechanism they choose.

Expected behavior: The behavior should be consistent, or clearly documented if intentionally different. (Personally, I think --no-color should produce fully ANSI-free output suitable for log files.)

How to Reproduce

This script sets up minimal docs and runs the test matrix. Just run it in a Python env that has Sphinx installed.

import os
from pathlib import Path
import subprocess
import sys
import tempfile


with tempfile.TemporaryDirectory() as tmp:
    src = Path(tmp) / "src"
    src.mkdir()
    (src / "conf.py").write_text("project = 'test'\n")
    (src / "index.rst").write_text("Test\n====\n")

    cases = [
        ("default", [], {}),
        ("--no-color", ["--no-color"], {}),
        ("NO_COLOR=1", [], {"NO_COLOR": "1"}),
    ]
    for name, args, extra_env in cases:
        env = os.environ.copy()
        env.pop("NO_COLOR", None)
        env.update(extra_env)
        command = [
            sys.executable, "-m", "sphinx", "-b", "html", *args,
            str(src), str(Path(tmp) / name),
        ]
        output = subprocess.run(
            command, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, env=env
        ).stdout
        print(f"**** {name} ****", repr(output), sep="\n")
Environment Information
Platform:              win32; (Windows-11-10.0.26200-SP0)
Python version:        3.14.2 (tags/v3.14.2:df79316, Dec  5 2025, 17:18:21) [MSC v.1944 64 bit (AMD64)])
Python implementation: CPython
Sphinx version:        9.1.0
Docutils version:      0.22.4
Jinja2 version:        3.1.6
Pygments version:      2.20.0
Sphinx extensions

Additional context

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No source file or test is named. Start by running the provided reproduction script on Windows and compare the output for --no-color and NO_COLOR=1; trace the CLI's terminal-formatting handling and identify the existing tests covering these options. Done means the two mechanisms have consistent ANSI behavior, with regression coverage for the reproduced case.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.