textwrap Splits Hyphenated CLI Flags Mid-Name by Default (tested)

A multi-word CLI flag like --enable-verbose-logging contains hyphens that are purely structural, not line-break hints. We measured what textwrap does with them by default, and it treats every hyphen as a valid place to break a line -- including inside Python's own argparse help output.

1. textwrap.wrap() breaks a flag name in half at an internal hyphen

import textwrap

text = "Use --enable-verbose-logging to print detailed output for debugging."
print(textwrap.fill(text, width=24))
Use --enable-verbose-
logging to print
detailed output for
debugging.

Measured: the flag name is split across two lines as --enable-verbose- and logging, with no indication it was ever one token. Someone skimming the wrapped text, or copy-pasting the flag to run it, gets a broken, unrunnable fragment.

2. This isn't theoretical -- argparse's own --help output hits it

import argparse

p = argparse.ArgumentParser(prog="mytool")
p.add_argument("-v", action="store_true",
    help="Equivalent to --enable-verbose-logging for backward compatibility with older scripts")
p.print_help()  # COLUMNS=40
options:
  -h, --help  show this help message
              and exit
  -v          Equivalent to --enable-
              verbose-logging for
              backward compatibility
              with older scripts

Measured: argparse's built-in help formatter wraps the help-text column using textwrap internally, so a flag name mentioned inside another option's description gets the exact same mid-name split, right in real, officially-generated --help output from the standard library.

3. Fix: break_on_hyphens=False for text that may contain flag names or identifiers

print(textwrap.fill(text, width=24, break_on_hyphens=False))
Use
--enable-verbose-logging
to print detailed output
for debugging.

Measured: with break_on_hyphens=False, the flag name is kept intact as a single unbroken unit and pushed to its own line instead of being split, even though it's longer than the configured width. argparse.ArgumentParser doesn't expose a parameter to pass this through to its internal formatter -- a custom HelpFormatter subclass is needed to change that behaviour there.

Frequently asked questions

Does textwrap break hyphenated words like CLI flag names by default?

Yes -- we measured break_on_hyphens defaulting to True, which treats any hyphen inside a word, including '--flag-name' style CLI options, as a valid line-break point.

Does Python's own argparse have this problem in real --help output?

Yes -- we reproduced it directly: when one option's help text mentions another option's hyphenated flag name, argparse's built-in formatter (which uses textwrap internally) splits the flag name across two lines.

How do I stop textwrap from splitting a hyphenated identifier?

Pass break_on_hyphens=False to textwrap.wrap() or textwrap.fill() -- we confirmed this keeps the whole hyphenated token on one line, pushing it down rather than breaking it.

Can I fix this for argparse's own --help output?

Not via a built-in parameter -- we found no option on ArgumentParser itself; you'd need to subclass argparse.HelpFormatter and override its wrapping to pass break_on_hyphens=False through.

Does this affect other hyphenated content like compound words?

Yes -- any hyphenated token (compound words, version strings, option flags) is subject to the same default splitting; it's not specific to CLI flags, just a very common place to notice it.

Written with AI assistance. Measured on 2026-10-04 with Python 3.13.5's built-in textwrap module: wrapped prose mentioning a hyphenated CLI flag name with textwrap.wrap()/fill() at default settings, then reproduced the identical split in real argparse --help output (COLUMNS=40) when one option's help text mentions another option's hyphenated name. PlainHeaders is our extension; Python's textwrap and argparse modules are built in.