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

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/

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

Something like 294d008?

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

This now falls back to no tags.

We still need formatting here?

Yes, updated to use colour if available.

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

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.

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

Here we go:

Thanks for the reviews, any further comments?

Would something like this be more maintainable?

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

Nice idea, updated :)

Documentation build overview

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

🔍 Preview build

5 files changed · ± 5 modified

± Modified

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?

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"

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"

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"

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"

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"

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"

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.

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

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.

Thanks, updated! How does this look?

LGTM. 👍

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("-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"

+              "         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"

-              "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"

-              "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"

+              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"

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

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

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

	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"

-              "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"

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

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

Uh oh!

Uh oh!

gh-148766: Add colour to Python help - #148767

gh-148766: Add colour to Python help#148767hugovk merged 7 commits intopython:mainpython/cpython:mainfrom hugovk:3.15-help-colourhugovk/cpython:3.15-help-colourCopy head branch name to clipboard

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

gh-148766: Add colour to Python help#148767
hugovk merged 7 commits into
python:mainfrom
hugovk:3.15-help-colour

hugovk commented Apr 19, 2026 •
edited by github-actions Bot
Loading

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