Rich OverflowMethod Options Explained: fold, crop, ellipsis, and ignore

Rich’s OverflowMethod provides four distinct strategies—fold, crop, ellipsis, and ignore—to control how content behaves when it exceeds the available console width.

The Textualize/rich library uses OverflowMethod throughout its rendering pipeline to handle text that exceeds column boundaries. Defined in rich/console.py as a Literal type, these options determine whether long lines wrap, truncate, or pass through to the terminal unchanged.

Understanding the OverflowMethod Type

In rich/console.py, the OverflowMethod type is defined at line 76 as a constrained string literal:

OverflowMethod = Literal["fold", "crop", "ellipsis", "ignore"]

This type annotation appears in method signatures across the codebase, including Console.print() and the ConsoleOptions class, ensuring consistent overflow handling throughout the rendering stack. When you pass an overflow option to a renderable, Rich propagates this value through ConsoleOptions to the underlying text processing logic.

The Four OverflowMethod Options

Each option serves a specific layout purpose, from preserving full content to hard truncation.

fold

The fold option wraps overflowing text onto subsequent lines without discarding any characters. Long lines convert into multiple lines that respect the console width constraint, preserving complete visibility of the content.

Use fold when displaying paragraphs, log messages, or tabular data where losing characters would corrupt the information. This is the preferred method for readable prose or when vertical space is cheaper than horizontal space.

crop

The crop option truncates the line exactly at the console width boundary, silently discarding any characters beyond that point. No visual indicator appears to signal the truncation.

Choose crop for fixed-width layouts where strict column alignment matters more than content completeness. This method ensures that multi-column displays maintain consistent widths without wrapping artifacts that could break formatting.

ellipsis

The ellipsis option truncates overflowing text and replaces the final three characters with an ellipsis symbol (…), providing immediate visual feedback that content has been omitted.

Select ellipsis when you need to maintain single-line displays while signaling to users that additional content exists. This works well for shortened file paths, truncated identifiers, or preview text where space constraints hide the full value.

ignore

The ignore option bypasses Rich’s overflow handling entirely, passing the renderable to the terminal without width constraints. The terminal’s native wrapping or clipping behavior determines the final output.

Use ignore when overflow is handled externally or when you require raw output without Rich’s intervention. The Pretty class in rich/pretty.py defaults to ignore (around line 173) to ensure that Python’s pretty-printed representations appear exactly as generated, without artificial line breaks that might alter the structured formatting.

Implementing OverflowMethod in Practice

You can specify overflow behavior when creating Text objects or calling Console methods. The Text class in rich/text.py accepts an overflow parameter in its constructor (documented around line 125), applying the strategy during the render phase.

from rich.console import Console
from rich.text import Text

console = Console(width=40)
long_text = "This is a very long string that exceeds the console width significantly"

# Fold wraps to next lines

console.print(Text(long_text, overflow="fold"))

# Crop cuts without warning

console.print(Text(long_text, overflow="crop"))

# Ellipsis shows truncation indicator

console.print(Text(long_text, overflow="ellipsis"))

The repository includes a working demonstration in examples/overflow.py, which iterates through the visible options to compare their visual output:

from rich.console import Console, OverflowMethod
from typing import List

console = Console()
supercali = "supercalifragilisticexpialidocious"

overflow_methods: List[OverflowMethod] = ["fold", "crop", "ellipsis"]
for overflow in overflow_methods:
    console.rule(overflow)
    console.print(supercali, overflow=overflow, style="bold blue")

When using Pretty for debugging output, note that it defaults to overflow="ignore" to preserve the exact formatting of Python object representations, preventing Rich from inserting line breaks that would distort the repr structure.

Summary

• fold wraps text to new lines, preserving all characters for maximum readability.
• crop hard-truncates at the width boundary, maintaining strict layout constraints without visual indicators.
• ellipsis truncates with a visible … marker, balancing space limits with user awareness of omitted content.
• ignore delegates overflow handling to the terminal, ideal for Pretty output or raw debugging displays.

Frequently Asked Questions

What is the default OverflowMethod in Rich?

Most Rich renderables default to fold for general text display, wrapping content to prevent data loss. However, specific classes like Pretty in rich/pretty.py override this to ignore to preserve the integrity of formatted Python representations.

Can I use OverflowMethod with any renderable?

Not all renderables accept overflow parameters directly. The Text class explicitly supports it, while containers like Table or Panel manage overflow through their own layout engines. Always check the specific renderable’s constructor in the source code to confirm overflow support.

How does fold differ from ignore?

fold actively wraps text at the console width boundary, inserting line breaks and increasing vertical height to preserve horizontal constraints. ignore passes the raw string to the terminal, which may wrap based on its own settings or allow horizontal scrolling, without Rich calculating line breaks.

When should I choose ellipsis over crop?

Select ellipsis when users need to know that content has been truncated, such as in file browsers or list views where hidden data exists. Use crop when the truncated portion provides no value and visual cleanliness matters more than truncation awareness, such as in fixed-width data columns where alignment trumps content visibility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}