gh-148766: Add colour to Python help by hugovk · Pull Request #148767 · python/cpython

hugovk · 2026-04-19T19:37:10Z

python --help (and especially --help-all) is a monochrome wall of text. Similar to argparse help, let's add some colour to add structure and improve readability.

Here's real screenshots of --help and termshot capture of --help-all:

Before	After
--help	--help

--help-all	--help-all

Issue: Add colour to Python help #148766

📚 Documentation preview 📚: https://cpython-previews--148767.org.readthedocs.build/

StanFromIreland · 2026-04-20T21:18:21Z

+#if defined(MS_WINDOWS) && defined(HAVE_WINDOWS_CONSOLE_IO)
+    {
+        DWORD mode = 0;
+        HANDLE handle = GetStdHandle(STD_OUTPUT_HANDLE);


Shouldn't this also consider stderr (or maybe it does? I don't know Windows quirks).

Something like 294d008?

StanFromIreland · 2026-04-20T21:19:33Z

+            PyMem_RawFree(buf);
+        }
+        else {
+            fprintf(f, usage_line, program);


If PyMem_RawMalloc fails we will get the raw tags, no?

This now falls back to no tags.

StanFromIreland · 2026-04-20T21:22:18Z

+            return;
+        }
+    }
+    fprint_tagged(stdout, usage_envvars, 0);


We still need formatting here?

Yes, updated to use colour if available.

serhiy-storchaka

What if the program path by accident contains {E}?

hugovk · 2026-04-21T15:19:04Z

Updated to flip it: colour codes are now included in the help text (via macros to keep it tidier), and stripped out when not needed.

So {E} in the path is not an issue.

hugovk · 2026-04-22T18:25:00Z

There are references to options and environment variables in descriptions. I would highlight them too.

Here we go:

hugovk · 2026-05-03T20:45:59Z

Thanks for the reviews, any further comments?

encukou · 2026-05-05T12:45:15Z

Would something like this be more maintainable?

#define RESET "\x1b[0m"
#define ENVVAR(STR)  "\x1b[1;36m" STR RESET

hugovk · 2026-05-05T13:28:44Z

Nice idea, updated :)

read-the-docs-community · 2026-05-05T13:31:30Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32560311 | 📁 Comparing 0a8ab45 against main (a8c9aa9)

🔍 Preview build

5 files changed · ± 5 modified

± Modified

serhiy-storchaka · 2026-05-05T13:38:01Z

This version is barely readable. What if return to the previous version with substitutions and use some of substitution codes to substitute the program name, the default PYTHONHOME, the path separator instead of just color sequences?

encukou · 2026-05-05T13:35:43Z

+SHORTOPT("-d") "     : turn on parser debugging output (for experts only, only works on\n"
+"         debug builds); also " ENVVAR_REF("PYTHONDEBUG") SUMMARY_LABEL("=x") "\n"
+SHORTOPT("-E") "     : ignore " ENVVAR_REF("PYTHON*") " environment variables (such as " ENVVAR_REF("PYTHONPATH") ")\n"
+SHORTOPT("-h") "     : print this help message and exit (also " SHORTOPT_SUMMARY("-?") " or " ENVVAR_REF("--help") ")\n"


Suggested change

SHORTOPT("-h") " : print this help message and exit (also " SHORTOPT_SUMMARY("-?") " or " ENVVAR_REF("--help") ")\n"

SHORTOPT("-h") " : print this help message and exit (also " SHORTOPT_SUMMARY("-?") " or " LONGOPT("--help") ")\n"

encukou · 2026-05-05T13:35:52Z

+"         this option has no effect on stdin; also " ENVVAR_REF("PYTHONUNBUFFERED") SUMMARY_LABEL("=x") "\n"
+SHORTOPT("-v") "     : verbose (trace import statements); also " ENVVAR_REF("PYTHONVERBOSE") SUMMARY_LABEL("=x") "\n"
+"         can be supplied multiple times to increase verbosity\n"
+SHORTOPT("-V") "     : print the Python version number and exit (also " ENVVAR_REF("--version") ")\n"


Suggested change

SHORTOPT("-V") " : print the Python version number and exit (also " ENVVAR_REF("--version") ")\n"

SHORTOPT("-V") " : print the Python version number and exit (also " LONGOPT("--version") ")\n"

encukou · 2026-05-05T13:37:18Z

-"PYTHON_FROZEN_MODULES: whether to use frozen modules; the default is \"on\"\n"
-"                  for installed Python and \"off\" for a local build\n"
-"                  (-X frozen_modules)\n"
+HEADING("These variables have equivalent command-line options (see ") ENVVAR_REF("--help") " for details):" "\n"


Suggested change

HEADING("These variables have equivalent command-line options (see ") ENVVAR_REF("--help") " for details):" "\n"

HEADING("These variables have equivalent command-line options") "(see " ENVVAR_REF("--help") " for details):" "\n"

encukou · 2026-05-05T13:38:22Z

-"PYTHONPERFSUPPORT: support the Linux \"perf\" profiler (-X perf)\n"
+ENVVAR("PYTHONINSPECT") "   : inspect interactively after running script (" SHORTOPT_SUMMARY("-i") ")\n"
+ENVVAR("PYTHONINTMAXSTRDIGITS") ": limit the size of int<->str conversions;\n"
+"                  0 disables the limit (" SHORTOPT_SUMMARY("-X") " " ENVVAR_REF("int_max_str_digits") SUMMARY_LABEL("=N") ")\n"


Suggested change

" 0 disables the limit (" SHORTOPT_SUMMARY("-X") " " ENVVAR_REF("int_max_str_digits") SUMMARY_LABEL("=N") ")\n"

" " SUMMARY_LABEL("0") " disables the limit (" SHORTOPT_SUMMARY("-X") " " ENVVAR_REF("int_max_str_digits") SUMMARY_LABEL("=N") ")\n"

encukou · 2026-05-05T13:38:59Z

+ENVVAR("PYTHONEXECUTABLE") ": set sys.argv[0] to this value (macOS only)\n"
 #endif
-"PYTHONHASHSEED  : if this variable is set to 'random', a random value is used\n"
+ENVVAR("PYTHONHASHSEED") "  : if this variable is set to 'random', a random value is used\n"


Suggested change

ENVVAR("PYTHONHASHSEED") " : if this variable is set to 'random', a random value is used\n"

ENVVAR("PYTHONHASHSEED") " : if this variable is set to '" SUMMARY_LABEL("random") "', a random value is used\n"

encukou · 2026-05-05T13:39:16Z

-"PYTHONMALLOCSTATS: print memory allocator statistics\n"
-"PYTHONPATH      : '%lc'-separated list of directories prefixed to the\n"
+ENVVAR("PYTHONMALLOCSTATS") ": print memory allocator statistics\n"
+ENVVAR("PYTHONPATH") "      : '%lc'-separated list of directories prefixed to the\n"


Suggested change

ENVVAR("PYTHONPATH") " : '%lc'-separated list of directories prefixed to the\n"

ENVVAR("PYTHONPATH") " : '" SUMMARY_LABEL(%lc) "'-separated list of directories prefixed to the\n"

serhiy-storchaka · 2026-05-05T13:50:03Z

My previous comment was related to the version prior to the latest change, but I still thing that substitution-based approach would be clearer than macros-based.

hugovk · 2026-05-05T13:53:39Z

@serhiy-storchaka Could you give a short example of what you're thinking of?

serhiy-storchaka · 2026-05-05T14:08:01Z

Simple example:

"{E}PYTHONHOME{r}      : alternate <prefix> directory (or <prefix>{b}{D}{r}<exec_prefix>).\n"
"                  The default module search path uses {b}{H}{r}.\n"

{E}, {b} and {r} substitute color sequences, {D} substitutes the DELIM character, {H} substitutes PYTHONHOMEHELP.

To avoid repeated {r} we can also change the syntax, for example:

"#E{PYTHONHOME}      : alternate <prefix> directory (or <prefix>#b{#D}<exec_prefix>).\n"
"                  The default module search path uses #b{#H}.\n"

This is simpler than it looks. #E{ and #b{ change the color, } resets it to default. We do not need to support arbitrary nesting.

hugovk · 2026-05-06T11:40:12Z

Thanks, updated! How does this look?

serhiy-storchaka

LGTM. 👍

hugovk · 2026-05-06T13:48:19Z

Thanks all for the reviews!

Add colour to Python help

cd43345

hugovk requested review from AA-Turner, FFY00 and ericsnowcurrently as code owners April 19, 2026 19:37

bedevere-app Bot added the awaiting core review label Apr 19, 2026

bedevere-app Bot mentioned this pull request Apr 19, 2026

Add colour to Python help #148766

Closed

hugovk added the interpreter-core (Objects, Python, Grammar, and Parser dirs) label Apr 19, 2026

StanFromIreland reviewed Apr 20, 2026

View reviewed changes

Comment thread Python/initconfig.c Outdated

StanFromIreland reviewed Apr 20, 2026

View reviewed changes

serhiy-storchaka reviewed Apr 21, 2026

View reviewed changes

Strip colour when not needed

e17d697

hugovk marked this pull request as draft April 21, 2026 15:25

bedevere-app Bot removed the awaiting core review label Apr 21, 2026

hugovk added 3 commits April 21, 2026 18:29

Check if Windows is using stdout/stderr

294d008

Use colour in fallback if available

4dddbb2

More colour in help text

b0837af

hugovk marked this pull request as ready for review April 22, 2026 18:17

bedevere-app Bot added the awaiting core review label Apr 22, 2026

Use function-like macros

e937914

encukou reviewed May 5, 2026

View reviewed changes

Change to substitution-based

0a8ab45

serhiy-storchaka approved these changes May 6, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels May 6, 2026

hugovk merged commit e7613f2 into python:main May 6, 2026
59 checks passed

hugovk deleted the 3.15-help-colour branch May 6, 2026 13:48

bedevere-app Bot removed the awaiting merge label May 6, 2026

	SHORTOPT("-h") " : print this help message and exit (also " SHORTOPT_SUMMARY("-?") " or " ENVVAR_REF("--help") ")\n"
	SHORTOPT("-h") " : print this help message and exit (also " SHORTOPT_SUMMARY("-?") " or " LONGOPT("--help") ")\n"

	SHORTOPT("-V") " : print the Python version number and exit (also " ENVVAR_REF("--version") ")\n"
	SHORTOPT("-V") " : print the Python version number and exit (also " LONGOPT("--version") ")\n"

	HEADING("These variables have equivalent command-line options (see ") ENVVAR_REF("--help") " for details):" "\n"
	HEADING("These variables have equivalent command-line options") "(see " ENVVAR_REF("--help") " for details):" "\n"

	" 0 disables the limit (" SHORTOPT_SUMMARY("-X") " " ENVVAR_REF("int_max_str_digits") SUMMARY_LABEL("=N") ")\n"
	" " SUMMARY_LABEL("0") " disables the limit (" SHORTOPT_SUMMARY("-X") " " ENVVAR_REF("int_max_str_digits") SUMMARY_LABEL("=N") ")\n"

	ENVVAR("PYTHONHASHSEED") " : if this variable is set to 'random', a random value is used\n"
	ENVVAR("PYTHONHASHSEED") " : if this variable is set to '" SUMMARY_LABEL("random") "', a random value is used\n"

	ENVVAR("PYTHONPATH") " : '%lc'-separated list of directories prefixed to the\n"
	ENVVAR("PYTHONPATH") " : '" SUMMARY_LABEL(%lc) "'-separated list of directories prefixed to the\n"

Uh oh!

Conversation

hugovk commented Apr 19, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

hugovk commented Apr 21, 2026

Uh oh!

hugovk commented Apr 22, 2026

Uh oh!

hugovk commented May 3, 2026

Uh oh!

encukou commented May 5, 2026

Uh oh!

hugovk commented May 5, 2026

Uh oh!

read-the-docs-community Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

serhiy-storchaka commented May 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka commented May 5, 2026

Uh oh!

hugovk commented May 5, 2026

Uh oh!

serhiy-storchaka commented May 5, 2026

Uh oh!

hugovk commented May 6, 2026

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hugovk commented May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hugovk commented Apr 19, 2026 •

edited by github-actions Bot

Loading

read-the-docs-community Bot commented May 5, 2026 •

edited

Loading