textwrap — wrapping and indenting text

textwrap.wrap, fill, dedent, indent, and shorten, checked on Python 3.13.12. Width is a character count, not a screen-column measurement.

模块页正文目前为英文。

The textwrap module reformats a single paragraph: wrap() returns a list of lines, fill() joins them with newlines, and shorten() collapses whitespace and truncates with a placeholder. indent() and dedent() adjust leading whitespace.

The width argument is described in the official documentation as a line width. The implementation measures each line with the string length (after optional tab expansion and whitespace normalization), not with East Asian display width, terminal cells, or a browser's rendered columns. A wide character such as "宽" still counts as 1 toward width, so a line can be wider on screen than the integer you passed.

Examples were run against Python 3.13.12.

Examples were checked against Python 3.13. See the official documentation for the complete API.

Python reference overview →

wrap, fill, and character width

wrap(text, width=70) reflows one paragraph and returns a list of lines, each at most width characters long unless a long word is left unbroken. fill() is "\n".join(wrap(...)). By default, tabs are expanded and other whitespace, including newlines, is turned into spaces before wrapping.

The second part of the example wraps twelve wide CJK characters with width=4. Each output line has length 4, even though those four characters are typically two cells wide in a terminal.

wrap and fill use a character count

textwrap.wrap(text, width=70, **kwargs)
textwrap.fill(text, width=70, **kwargs)

wrap() returns a list of lines; fill() returns one string. width counts characters, not screen columns.

ParameterDescription
textA single paragraph. Newlines inside the text are treated as whitespace by default.
widthMaximum length of each wrapped line, measured with len() after the default whitespace processing. The default is 70. It is not a display-cell budget.
kwargsPassed to TextWrapper: initial_indent, subsequent_indent, expand_tabs, tabsize, replace_whitespace, break_long_words, and others documented on the class.

Returns: wrap() returns a list of strings without trailing newlines. fill() returns a single string with newlines between lines.

python
import textwrap

text = 'Compare two files and highlight every inserted or deleted line.'
print(textwrap.wrap(text, width=20))
print(textwrap.fill(text, width=20))
wide = '宽度测试宽度测试宽度测试'
lines = textwrap.wrap(wide, width=4)
print(lines)
print([len(line) for line in lines])

Expected output

['Compare two files', 'and highlight every', 'inserted or deleted', 'line.']
Compare two files
and highlight every
inserted or deleted
line.
['宽度测试', '宽度测试', '宽度测试']
[4, 4, 4]

Related: str methods, unicodedata east_asian_width

Official documentation →

dedent, indent, and shorten

dedent() removes the common leading whitespace from every line in the text. Lines that contain only whitespace are normalized. indent() adds a prefix to selected lines (by default, lines that contain a non-whitespace character).

shorten() collapses whitespace to single spaces and truncates to at most width characters, appending a placeholder (default "[...]") if it has to drop words. The width is again a character count, not a screen-column measurement.

dedent, indent, and shorten

textwrap.dedent(text)
textwrap.indent(text, prefix, predicate=None)
textwrap.shorten(text, width, **kwargs)

dedent() strips shared indentation. indent() adds a prefix. shorten() truncates a collapsed paragraph to a character budget.

ParameterDescription
textThe input string. dedent() looks at leading whitespace on each line.
prefixThe string prepended by indent(). It counts toward wrap width only if you also wrap later; indent() itself does not wrap.
predicateOptional callable for indent(). When omitted, lines that contain a non-whitespace character are indented.
widthFor shorten(), the maximum character length of the result, including the placeholder.

Returns: A new str. The example prints trailing newlines that are already present on the indented block.

python
import textwrap

block = '  line one\n    line two\n  line three\n'
dedented = textwrap.dedent(block)
print(dedented)
print(textwrap.indent(dedented, '> '))
text = 'Compare two files and highlight every inserted or deleted line.'
print(textwrap.shorten(text, width=24))

Expected output

line one
  line two
line three

> line one
>   line two
> line three

Compare two files [...]

Related: wrap and fill, str methods

Official documentation →