Rich is a Python library for rendering rich text and beautiful formatting in the terminal. It provides an API for adding color, style, tables, progress bars, markdown, syntax highlighting, tracebacks, and more to terminal output with minimal code.
Key Characteristics:
| Characteristic | Detail |
|---|---|
| Rendering protocol | __rich_console__() and __rich_measure__() on any object |
| Central coordinator | Console class in rich/console.py |
| Atomic output unit | Segment named tuple in rich/segment.py |
| Platform support | Linux, macOS, Windows |
| Python requirement | Python 3.8+ |
For getting started examples, see page 1.1 (Getting Started). For architectural details, see page 1.2 (Architecture Overview).
Sources: README.md30-32 pyproject.toml6 pyproject.toml31
Install using pip:
Test Rich output on your terminal:
Dependencies:
pygments (≥2.13.0) - syntax highlightingmarkdown-it-py (≥2.2.0) - markdown parsingipywidgets (≥7.5.1,<9) for Jupyter supportSources: README.md47-58 pyproject.toml30-37
Rich addresses common terminal application needs:
| Capability | Implementation |
|---|---|
| Text styling | Console.print() with markup or style parameter |
| Structured data display | rich.table.Table, rich.tree.Tree |
| Progress tracking | rich.progress.Progress, rich.progress.track() |
| Enhanced tracebacks | rich.traceback.Traceback, rich.traceback.install() |
| Terminal adaptation | Automatic color system detection via Console |
| Live updates | rich.live.Live, Console.status() |
| Standard library integration | rich.logging.RichHandler, rich.pretty.install() |
The library abstracts ANSI escape codes and terminal control sequences, providing a high-level protocol-based API.
Sources: README.md30-34 README.md136-246
System Architecture
The Console class (rich/console.py) is the central coordinator. All renderables implement the Renderable protocol with __rich_console__() and __rich_measure__() methods. Output is generated as Segment instances containing text, Style, and control codes.
Sources: README.md84-94 Diagram 1 from provided architecture diagrams
Rendering Flow (High to Low Level)
Rendering Process:
__rich_measure__() determines minimum and maximum widths (rich/console.py)__rich_console__() yields Segment instances with text and StylePanel contains another renderable)Text objects with styled Span rangesSegment methods (rich/segment.py)Segment instances converted to ANSI escape sequences for terminalSources: README.md84-94 Diagram 2 from provided architecture diagrams
Core Protocols
Key Protocols:
ConsoleRenderable: Objects with __rich_console__() and __rich_measure__() methodsRichCast: Objects with __rich__() that return a renderableRenderableType: Union accepting str, ConsoleRenderable, or RichCastAny object implementing ConsoleRenderable can be printed by Console. The protocol receives Console and ConsoleOptions context, yields Segment instances, and returns Measurement for layout calculations.
Sources: README.md424-425 Diagram 3 from provided architecture diagrams, rich/console.py rich/segment.py rich/text.py
Component Overview
| Renderable | Module | Purpose | Key Methods |
|---|---|---|---|
Text | rich.text | Styled text with spans | stylize(), highlight_regex(), from_markup() |
Table | rich.table | Tabular data with borders | add_column(), add_row(), add_section() |
Panel | rich.panel | Bordered content container | Panel() constructor with renderable |
Progress | rich.progress | Multiple progress bars | add_task(), update(), track() |
Tree | rich.tree | Hierarchical data display | add(), with guide lines |
Syntax | rich.syntax | Code with highlighting | Uses Pygments lexers, configurable themes |
Markdown | rich.markdown | Markdown rendering | Uses markdown-it-py parser |
Pretty | rich.pretty | Object pretty printing | pprint(), @auto decorator |
Traceback | rich.traceback | Enhanced stack traces | install(), syntax highlighting |
Layout | rich.layout | Grid-based arrangement | split_column(), split_row() |
Columns | rich.columns | Column-based layout | Columns(renderables) |
Group | rich.console | Group multiple renderables | Group(*renderables) |
Sources: README.md136-376
Console Core Systems
The Console class manages:
Theme classSources: rich/console.py Diagram 4 from provided architecture diagrams
Operating Systems:
Python Versions:
Environments:
Color Support:
Environment variables that influence behavior:
| Variable | Effect |
|---|---|
FORCE_COLOR | Force color output on (non-empty value) |
NO_COLOR | Disable all color output (non-empty value) |
TTY_COMPATIBLE | Override auto-detection of TTY support |
TTY_INTERACTIVE | Override auto-detection of interactive mode |
TERM | Terminal type detection |
COLORTERM | True color support detection (truecolor or 24bit) |
COLUMNS / LINES | Override terminal dimensions |
JUPYTER_COLUMNS / JUPYTER_LINES | Override console size in Jupyter |
UNICODE_VERSION | Override Unicode version for cell-width calculations |
Sources: README.md40-44 pyproject.toml10-26 CHANGELOG.md82-93 CHANGELOG.md63-80 CHANGELOG.md27-51
Here's a simple example demonstrating Rich's basic capabilities:
For more examples and detailed information about specific features, see the respective feature pages in this wiki.
Sources: README.md61-68 README.md212-239
Rich provides a comprehensive solution for creating visually appealing and information-rich terminal applications in Python. By abstracting away the complexity of terminal formatting, it allows developers to focus on content rather than implementation details.
Sources: README.md30-32 README.md424-425
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.