Core Rendering System

Relevant source files

• docs/source/console.rst
• rich/color.py
• rich/console.py
• rich/segment.py
• rich/style.py
• tests/test_color.py
• tests/test_console.py
• tests/test_segment.py
• tests/test_style.py

Purpose and Scope

The Core Rendering System is the foundational infrastructure that powers all terminal output in Rich. It consists of four major components:

Component	File	Purpose
Console	rich/console.py	Central coordinator; manages terminal output, buffering, threading
ConsoleOptions	rich/console.py	Carries rendering context (width, encoding, etc.) through the pipeline
Segment	rich/segment.py	Atomic unit of styled text output
Style / Color	rich/style.py, rich/color.py	Visual attributes attached to segments

Detailed documentation for each component is in the child pages:

• Console (2.1) — Constructor parameters, color detection, all public methods
• Rendering Pipeline (2.2) — Protocol resolution, render() vs render_lines(), buffering, RenderHook
• Segments (2.3) — Segment operations, ANSI decoding, Unicode cell-width
• Styles and Colors (2.4) — Style and Color classes, color systems, ANSI rendering

For information about specific renderables like Tables and Panels, see Renderables (4). For live updating displays, see Live Updates (5).

System Architecture

Data flow: user code → terminal output

Sources: rich/console.py587-758 rich/console.py118-250 rich/segment.py64-79 rich/style.py36-84

Console: The Central Coordinator

The Console class is the primary interface for all Rich output. It manages terminal detection, color systems, output files, threading, and coordinates the entire rendering process. See Console (2.1) for full details.

Key Configuration Parameters

rich/console.py587-758

Parameter	Type	Purpose
color_system	str	Color capability: "auto", "standard", "256", "truecolor", "windows"
force_terminal	Optional[bool]	Override terminal detection
width / height	int	Override terminal dimensions
file	IO[str]	Output destination (defaults to stdout)
record	bool	Enable recording for export to HTML/SVG/text
legacy_windows	bool	Enable legacy Windows console mode
no_color	Optional[bool]	Strip all color from output
style	StyleType	Apply a global style to all output

Console internal components:

Sources: rich/console.py625-758 rich/console.py795-817 rich/console.py937-983 rich/console.py542-548

Core Rendering Methods

The Console provides a layered API for output:

Console public API → internal rendering chain:

Sources: rich/console.py1124-1248 rich/console.py1389-1506 rich/console.py1657-1741

ConsoleOptions: Rendering Context

ConsoleOptions is a dataclass that carries rendering configuration through the pipeline. Every __rich_console__ method receives a ConsoleOptions instance.

rich/console.py118-250

Structure

Field	Type	Description
size	ConsoleDimensions	Width and height of the console
legacy_windows	bool	Whether to use legacy Windows mode
min_width	int	Minimum width constraint
max_width	int	Maximum width constraint
is_terminal	bool	Whether output is to a terminal
encoding	str	Character encoding (e.g., "utf-8")
max_height	int	Height of container
justify	Optional[JustifyMethod]	Text justification override
overflow	Optional[OverflowMethod]	Overflow handling override
no_wrap	bool	Disable text wrapping
highlight	Optional[bool]	Enable syntax highlighting
markup	Optional[bool]	Enable markup processing
height	Optional[int]	Current height constraint

Methods

update() rich/console.py163-198 - Returns a copy with modified values. Supports updating width, min_width, max_width, justify, overflow, no_wrap, highlight, markup, and height.

update_width(width) rich/console.py200-211 - Convenience method to update both min_width and max_width.

update_height(height) rich/console.py213-224 - Updates height and max_height.

ascii_only property rich/console.py148-151 - Returns True if encoding doesn't start with "utf".

Sources: rich/console.py118-250

The Renderable Protocol

Any object can be rendered by implementing the ConsoleRenderable protocol. This protocol-based design enables Rich's extensibility. See Rendering Pipeline (2.2) for detailed mechanics.

Renderable type hierarchy:

Sources: rich/console.py252-278 rich/measure.py15-40

__rich_console__ Method

Core rendering method. Receives a Console instance and ConsoleOptions, and yields either more RenderableType objects (for recursive rendering) or Segment instances (for final output).

rich/console.py263-270

__rich_measure__ Method

Optional method that returns the minimum and maximum width a renderable needs. Used by the layout system to calculate optimal widths.

Returns a Measurement namedtuple with:

• minimum — smallest width that can display the content
• maximum — ideal width for the content

rich/measure.py15-40

Rendering Pipeline

See Rendering Pipeline (2.2) for full detail. Below is a high-level summary.

console.render() resolution flow:

Sources: rich/console.py1389-1457 rich/console.py1509-1566 rich/protocol.py8-25

Rendering Process Steps

rich/console.py1389-1457

1. Protocol resolution — rich_cast() resolves __rich__() before further dispatch
2. Type dispatch — distinguishes strings, ConsoleRenderable, and non-renderable objects
3. Recursive rendering — objects may yield other renderables, forming a render tree
4. Segment collection — leaf renderables yield Segment instances
5. Buffering — segments accumulate in _buffer when _buffer_index > 0 (capture/pager/context manager)
6. ANSI conversion — _render_buffer() serializes segments to ANSI escape strings
7. File write — result string is written to Console.file

Sources: rich/console.py1389-1457 rich/console.py819-826

Segments: Atomic Rendering Units

Segment is the final output unit in Rich's rendering pipeline — a piece of text with an optional Style and optional control codes. See Segments (2.3) for full detail.

rich/segment.py64-79

Segment(NamedTuple):
    text:    str
    style:   Optional[Style]              # visual attributes
    control: Optional[Sequence[ControlCode]]  # cursor/screen control codes

Key Properties and Methods

Method / Property	Purpose
cell_length	Terminal cell count (accounts for wide characters via cell_len())
is_control	True if control field is set
split_cells(cut)	Split at a cell position; handles double-width characters
apply_style(segments, style)	Prepend a style to an iterable of segments
split_lines(segments)	Split on newlines → Iterable[List[Segment]]
split_and_crop_lines(segments, length)	Split + crop each line to length cells
adjust_line_length(line, length)	Crop or pad a single line to exact cell length
simplify(segments)	Merge adjacent segments with identical style
strip_styles(segments)	Remove all style objects
strip_links(segments)	Remove only hyperlinks from styles
divide(segments, cuts)	Split segment stream at specified cell positions

Sources: rich/segment.py82-699

Segment operation data flow:

Sources: rich/segment.py190-699

Cell Length and Wide Characters

cell_length uses cell_len() from rich/cells.py to compute terminal width. split_cells(cut) correctly handles double-width characters (CJK, emoji): if a cut falls inside a 2-cell character, it replaces it with two spaces.

Sources: rich/segment.py82-89 rich/segment.py158-182

Control Codes

Segments with a non-None control field carry terminal control operations instead of printable text. The ControlType enum (in rich/segment.py) enumerates supported operations:

ControlType	Effect
BELL	Terminal bell
CARRIAGE_RETURN	Move to start of line
HOME	Move cursor to home
CLEAR	Clear screen
SHOW_CURSOR / HIDE_CURSOR	Cursor visibility
ENABLE_ALT_SCREEN / DISABLE_ALT_SCREEN	Alternate screen buffer
CURSOR_UP/DOWN/FORWARD/BACKWARD	Relative cursor movement
CURSOR_MOVE_TO_COLUMN / CURSOR_MOVE_TO	Absolute cursor positioning
ERASE_IN_LINE	Clear to end of line
SET_WINDOW_TITLE	Set terminal window title

Sources: rich/segment.py35-60

Styles and Colors: Summary

Style and Color carry the visual attributes attached to every Segment. See Styles and Colors (2.4) for full detail.

Style rich/style.py36-84 holds:

• Foreground and background Color objects
• Boolean attribute flags (bold, italic, underline, etc.) encoded as bitfields
• Optional hyperlink (link)
• Optional metadata dict (used by Textual for event handling)

Styles are parsed from strings like "bold red on black" via Style.parse() rich/style.py493-557 combined with + or Style.chain(), and serialized back to ANSI escape sequences via _make_ansi_codes() rich/style.py340-381

Color rich/color.py302-568 supports four color types:

ColorType	Example	Range
DEFAULT	"default"	Terminal default color
STANDARD	"red", "bright_blue"	16 named ANSI colors
EIGHT_BIT	"color(200)"	256-color palette
TRUECOLOR	"#ff0000", "rgb(255,0,0)"	16.7 million colors

Colors are automatically downgraded to the ColorSystem detected by the Console via Color.downgrade() rich/color.py512-568

Sources: rich/style.py36-84 rich/style.py340-381 rich/style.py493-557 rich/color.py21-28 rich/color.py302-568

Rendering Flow: Code to Terminal

End-to-end call chain with code entity names:

Sources: rich/console.py1389-1457 rich/style.py340-381 rich/protocol.py8-25

Thread Safety and Buffering

The Console is thread-safe through thread-local storage (ConsoleThreadLocals) and a reentrant lock (threading.RLock).

rich/console.py542-548 rich/console.py720

Thread-Local State (ConsoleThreadLocals):

Field	Purpose
theme_stack	Per-thread ThemeStack
buffer	List[Segment] — accumulated segments
buffer_index	Nesting depth of buffer contexts

Buffering:

• _enter_buffer() / _exit_buffer() rich/console.py819-826 increment/decrement buffer_index
• When buffer_index > 0, segments accumulate in _buffer instead of being written immediately
• Used by capture(), pager(), and the Console context manager (__enter__ / __exit__)

Recording:

• When record=True, output is also copied to _record_buffer rich/console.py754
• Enables export via export_text(), export_html(), export_svg() — see Export and Capture (7.4)

Sources: rich/console.py542-548 rich/console.py750-757 rich/console.py819-826

ANSI Code Generation

The final step in the pipeline converts Segment instances to ANSI escape sequences via Console._render_buffer().

_render_buffer() behavior:

1. Iterates through Segment instances
2. Tracks the current Style state; emits ANSI codes only on style changes (optimization)
3. Converts control segments to ANSI sequences (cursor movement, screen control)
4. Normalizes text (emoji substitution, encoding handling)
5. Appends reset codes (\x1b<FileRef file-url="https://github.com/Textualize/rich/blob/fc41075a/0m) when a styled run ends\n\nStyle → ANSI path#LNaN-LNaN" NaN file-path="0m`) when a styled run ends\n\nStyle → ANSI path">Hii produces SGR parameter strings

• Color.downgrade(system) rich/color.py512-568 maps truecolor/256-color down to the terminal's ColorSystem
• On legacy Windows, a different output path is used (see Platform Support (7.3))

Sources: rich/style.py340-381 rich/color.py512-568

Integration with High-Level Renderables

High-level renderables implement the protocol to produce Segments:

For detailed information on these renderables, see Renderables.

Sources: rich/table.py rich/panel.py rich/text.py rich/syntax.py rich/progress.py