sphinx-doc / sphinx-doc/sphinx
Mismatch between --no-color and NO_COLOR behavior in Sphinx 9.1.0 on Windows
Nobody has claimed this yet.
- 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:
--no-colorstill outputs ANSI control sequences (not colorized text, but cursor/line control sequences like\x1b[2K) on my Windows setup.NO_COLOR=1does 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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