Add colour to `argparse` help

[hugovk]

Feature or enhancement

In Python 3.13 we added colour output to the new REPL, traceback and doctest, and in 3.14 to unittest, test.regrtest and calendar, that can also be controlled with the PYTHON_COLORS, NO_COLOR and FORCE_COLOR environment variables:

• https://docs.python.org/3.14/whatsnew/3.14.html#unittest
• https://docs.python.org/3.14/using/cmdline.html#using-on-controlling-color

Let's add colour to argparse help output.

Survey

First, here's a survey of some other CLIs that use colour:

Survey

uv
cargo
composer
ruff
lsd
fd
	See also: bat, hyperfine, oxipng, zizmor
gh
rich-cli
typer

These fall into four groups:

• uv/cargo: green + cyan
• composer: yellow + green
• ruff/lsd/fd/gh: only bold
• typer/rich-cli: green + cyan + yellow

Prototypes

I've made prototypes of two of these (uv/cargo style, typer/rich-cli style), and another with blue + magenta similar to the 3.13 REPL/traceback.

Prototypes

main
uv/cargo style
typer/rich-cli style
REPL style

I think I prefer the typer/rich-cli style: the extra colour makes it easier to pick out the (green) short options from the (cyan) long options, and from their (green) arguments. And it should also be somewhat familiar to Python users who have used typer-based CLIs.

Linked PRs

• gh-130645: Add colour to argparse help #132323
• gh-130645: Add color to stdlib argparse CLIs #133380
• GH-130645: Default to color help in argparse #136809
• [3.14] GH-130645: Default to color help in argparse (GH-136809) #136886

[rhettinger]

I don't think this should be done.

[StanFromIreland]

Image links don't work in the survey.

I'd vote for REPL style. It's not bombarding you with color and the magenta/purple is generally visible in all terminal styles.

Raymond could you please clarify why? We already have some color in the REPL and there are ongoing efforts to add more (#130472) so it seems people are generally in favor of color.

Edit: Seeing it now, I think the simple ruff style would be fine, what do you think @rhettinger, about a very simple coloring?

[hugovk]

Image links don't work in the survey.

Thanks, fixed.

[AlexWaygood]

Are you aware of the rich-argparse project (https://github.com/hamdanal/rich-argparse)? I use it in my typeshed-stats project, and it's very nice indeed. This is all I need to do to add colour to my argparse-based CLI in that project; everything else is just stdlib argparse.

[sobolevn]

I think that adding an option (which is off by default) is a good idea, but argparse must stay colorless by default, too many tests in the wild depend on it.

[rhettinger]

If you end-up doing this over my objections (no major standard command-line tool does this), then it must be opt-in.

Also, the bulk of the code should be in a separate submodule that is only imported with needed. Start-up time is a critical issue for argparse. We've worked hard to avoid dependencies and to have a fast load time.

Also, the choice of colors really matters. Bad choices can impair usability for all users, or for users with the particular choice of light or dark backgrounds, or for users with vision issues including various kinds of color blindness. IPython is an example of a tool that made poor choices. When running ?? to look at source code against a black background, IPython displays operators like =, +, or parens in a dark blue that is very hard to read.

AFACIT, no group of users has ever requested this feature even though this is a heavy used, popular module. ISTM that the OP is doing this as part of a "sweep" across modules (such as unittest) without considering the whether the existing users of the module want or need this.

[rhettinger]

Example of IPython's impaired readability with a poor choice of colors (the assignments, multiplications, and function calls are almost invisible and the docstring is challenging as well):

[hugovk]

Are you aware of the rich-argparse project (hamdanal/rich-argparse)?

I wasn't, thanks for sharing. I think this would still be useful in the stdlib, for when you want to keep your dependencies to a minimum, and rich (plus its dependencies) is a fairly large package.

I think that adding an option (which is off by default) is a good idea, but argparse must stay colorless by default, too many tests in the wild depend on it.

Yes, it can be opt-in. And the existing PYTHON_COLORS and NO_COLOR env vars can also be used.

Start-up time is a critical issue for argparse. We've worked hard to avoid dependencies and to have a fast load time.

Agreed, this is important.

Also, the choice of colors really matters. Bad choices can impair usability for all users, or for users with the particular choice of light or dark backgrounds, or for users with vision issues including various kinds of color blindness. IPython is an example of a tool that made poor choices. When running ?? to look at source code against a black background, IPython displays operators like =, +, or parens in a dark blue that is very hard to read.

Absolutely, colour choice and accessibility is important. This is why I've surveyed popular existing tools and picked colours with good contrast, and none of those or my suggestsions use that blue. And @ambv is adding theming support this month, see: #130472 (comment).

AFACIT, no group of users has ever requested this feature even though this is a heavy used, popular module.

Here's some people wanting colour help in argparse:

• "In argparse, I've always wanted a way to make colored help text like those of poetry and pipenv." python/cpython#86189
• "A drop-in replacement would be nice so I don't have to switch from argparse to something else in all my projects." Textualize/rich#2258
• "I'd also like to know how to properly color the --help output with colorama." https://stackoverflow.com/questions/69980467/argparse-remove-whitespace-after-flags-in-help-and-colorizing-help-output-wit

I think the use of colour in third-party CLI replacements and rich-argparse also points to a demand.

ISTM that the OP is doing this as part of a "sweep" across modules (such as unittest) without considering the whether the existing users of the module want or need this.

Yes, now that we added colour support in 3.13 for the REPL and tracebacks, I'm looking to see where else we can improve the experience over plain monochrome output. Colour can be extremely helpful. unittest is a great example: coloured pytest output has long been very useful for finding the error(s) in long test logs. And it's now much easier to find errors in our own CI logs since unittest and test.regrtest have colour output.

Example of IPython's impaired readability with a poor choice of colors (the assignments, multiplications, and function calls are almost invisible and the docstring is challenging as well):

This is a good example of poor colour choice, thanks. This blue won't be used. As it happens, IPython 9.0.0 was released on Friday with much improved colours!

[savannahostrowski]

I'm +1 on this, if it's opt-in and ensures that we can ensure the startup time isn't impacted. In CLI tools that I've worked on in the past, we leaned heavily on the ANSI defined color presets when trying to guarantee accessibility/sufficient contrast.