Add support for colorizing code examples in argparse description/epilog

Today, argparse does not support any native way to colorize code snippets in help descriptions. Example commands blend in with surrounding text, making help output harder to scan:

Allowing users to specify that they want to colorize an example in help text is a common UX pattern in modern CLI frameworks. Both Typer and rich-click support markup in help text via Rich's console markup (e.g., [green]text[/green]). Now that argparse supports colorization, it would be nice to add similar functionality. I think this is perhaps the last remaining gap in argparse's colorization support. I'm proposing a limited semantic markup approach:

epilog="""Examples:
  [cmd]python -m myapp --verbose run[/cmd]
"""

After:

This support could potentially be expanded out later to support more sophisticated syntax highlighting (e.g. [python]...[/python]), since we already have a lot of this tokenization logic in place in _colorize.py. However, I'd like to start here before boiling the ocean.

Linked PRs

@hugovk

cc: @hugovk as well for his thoughts

Can we have a separate formatter class to avoid supporting this markup? or a way to disable this (how do we type a literal [cmd]<text>[/cmd]; do we need backslashes?) A general markup=False option would be great to disable any interpreted markup I think (the same way we disable colors).

I think the intent of this feature is a bit different than the other Formatters we support today (which support the layout of help). Another option would be to not transform the input when color=False, which would be fairly straightforward to handle. I'm not super concerned about users literally typing [cmd]...[/cmd] though. I did check on GitHub search and found no instances of that. Ideally this would also be pretty lightweight for users to opt into as well.

I think that today it may be more practical to support a subset of Markdown (*italic*, **bold**, `code`, ```other code```, rewrapped paragraphs, enumeration lists, etc) in argparse and pydoc. But it should not be enabled by default. We can support also other bb-codes ([i]italic[/i], [b]bold[/b], [code]code[/code]) and html (<i>italic</i>, <b>bold</b>, <code>code</code>) in other formatters. This is a large issue.

I believe that BB code would be awesome. We could also support a more generic [color=...][/color] because it would really give more customization power to users. I also agree that I would rather have it disabled by default because I personally won't be using everywhere.

I think that users can currently do this epilog=f"{t.prog} my-tool -m alpha{t.reset}" (See example below). It's unclear if the cmd= layer of indirection is providing enough value.
The [cmd] style might be better as subset of Markdown (as someone else mentioned)
If you add epilog= this will immediately motivate description= and friends for consistency. This creates a large potential of feature creep with non-trivial unexpected complexity (See example below)
If you want to support multiple versions of Python, all of these API changes are going to require if sys.version_info >= (3, 15) and /or if sys.version_info >= (3, 14) sprinkled around in your code.

People will probably figure that you can manually put escape sequences in fields and it sort of works. Maybe It's a good idea to be proactive to either discourage or enable this?

import sys
from argparse import ArgumentParser
from _colorize import get_theme

t = get_theme().argparse

def get_parser() -> ArgumentParser:
    p = ArgumentParser(description=f"Example {t.usage}Color Tool{t.reset}",
                       epilog=f"Example {t.heading}Color Tool{t.reset}")
    p.add_argument('-i', '--input', help=f"Input {t.usage}file{t.reset}", metavar="FILE")
    return p


if __name__ == "__main__":
    p = get_parser()
    pa = p.parse_args()
    print(pa)
    sys.exit(0)

I think something like this would be good. Quick demo:

But then these plaintext [cmd]s are a bit annoying with NO_COLOR:

I first thought, for NO_COLOR we could replace them with backticks. But my CLI currently does use backticks in those positions and I'd modified them to [cmd] for this demo, so triggering on backticks would be useful -- colour when supported, and understandable backticks for NO_COLOR:

One downside of a generic code formatting is we're losing the semantic meaning: [cmd] is a command with the same magenta of the prog in the usage line. If I add something like * and `--help` for help to the description it's also shown in magenta when we might prefer it in cyan:

But maybe this is overthinking things, and a subset of Markdown would be best. Keep the subset small to begin with. I'd skip BBCode, as Markdown is more familiar and looks okay in plaintext as well. So it could be on by default, and actually doesn't need a toggle beyond NO_COLOR and friends.

Yeah, my intention here was to keep things minimal. I don't want to go down the rabbit hole of implementing a full Markdown parser to solve a pretty simple, contained, and common issue.

If someone wants to scope a larger proposal for something more robust, I think that's fine but beyond the scope of what I'm after.

GH-142389: Add backtick markup support in description and epilog (#14…

Using this to add some colour to regrtest and pdb's help descriptions: #149332.

gh-142389: Add colour to regrtest and pdb's help descriptions (#149332)

gh-142389: Add backticks to stdlib argparse help to display in colour (…

gh-142389: Add support for backtick colorisation in argparse help text (

Navigation Menu

Repository navigation

Add support for colorizing code examples in argparse description/epilog #142389

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Add support for colorizing code examples in argparse description/epilog #142389

Description

Linked PRs

Activity

savannahostrowski commented on Dec 7, 2025

picnixz commented on Dec 7, 2025

savannahostrowski commented on Dec 7, 2025

serhiy-storchaka commented on Dec 8, 2025

picnixz commented on Dec 8, 2025

mpkocher commented on Dec 9, 2025

hugovk commented on Dec 12, 2025

savannahostrowski commented on Dec 12, 2025

hugovk commented on May 3, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions