This page covers the Console class in rich/console.py: its constructor parameters, terminal capability detection, color system selection, environment variable handling, thread safety, and all public methods. For the rendering pipeline that Console drives, see Rendering Pipeline. For style and color details, see Styles and Colors. For export functionality (HTML, SVG, text), see Export and Capture.
Console is the central class in Rich. Every rendering operation — printing text, drawing tables, showing progress bars — flows through a Console instance. It owns the output file handle, terminal capability state, style theme, thread lock, and output buffer. All other Rich renderables ultimately depend on a Console to convert themselves into terminal output.
Diagram: Console and its dependencies
Sources: rich/console.py1-64
Console.__init__ accepts only keyword arguments. The full signature is at rich/console.py625-658
| Parameter | Type | Default | Purpose |
|---|---|---|---|
color_system | str | None | "auto" | Color system: None, "auto", "standard", "256", "truecolor", "windows" |
force_terminal | bool | None | None | Override terminal detection; None = auto-detect |
force_jupyter | bool | None | None | Override Jupyter detection; None = auto-detect |
force_interactive | bool | None | None | Override interactive mode; None = auto-detect |
soft_wrap | bool | False | Default soft-wrap for print() |
theme | Theme | None | None | Style theme; None uses themes.DEFAULT |
stderr | bool | False | Write to sys.stderr instead of sys.stdout |
file | IO[str] | None | None | Explicit output file; overrides stderr |
quiet | bool | False | Suppress all output |
width | int | None | None | Fixed width; auto-detected if None |
height | int | None | None | Fixed height; auto-detected if None |
style | StyleType | None | None | Global style applied to all output |
no_color | bool | None | None | Disable color; None reads NO_COLOR env var |
tab_size | int | 8 | Spaces per tab character |
record | bool | False | Buffer output for later export (required by export_* methods) |
markup | bool | True | Enable console markup by default |
emoji | bool | True | Enable emoji code substitution |
emoji_variant | EmojiVariant | None | None | Force "text" or "emoji" variant |
highlight | bool | True | Enable automatic highlighting via highlighter |
log_time | bool | True | Show timestamp in log() output |
log_path | bool | True | Show caller file/line in log() output |
log_time_format | str | Callable | "[%X]" | strftime format string or callable for timestamps |
highlighter | HighlighterType | None | ReprHighlighter() | Default auto-highlighter |
legacy_windows | bool | None | None | Force legacy Windows mode; None = auto-detect |
safe_box | bool | True | Restrict box characters to those safe on legacy Windows |
get_datetime | Callable[[], datetime] | None | None | Override for datetime.now (used in log()) |
get_time | Callable[[], float] | None | None | Override for time.monotonic (used in log()) |
Sources: rich/console.py587-658
When color_system="auto" (the default), Console._detect_color_system() is called at construction time. Detection proceeds as follows:
Diagram: Color system detection flow
Sources: rich/console.py795-817 rich/console.py102-106
The ColorSystem enum values map to string names via COLOR_SYSTEMS and _COLOR_SYSTEMS_NAMES dictionaries rich/console.py531-538
is_terminal and is_dumb_terminalConsole.is_terminal is a property that checks whether the output file is connected to a real terminal. It is influenced by:
force_terminal constructor argument (sets _force_terminal)FORCE_COLOR environment variable (treats terminal as TTY if set and non-empty)TTY_COMPATIBLE environment variable ("1" → terminal, "0" → not terminal)fileno() comparison against _STD_STREAMS_OUTPUTConsole.is_dumb_terminal returns True when TERM is "dumb" or "unknown", which suppresses color and cursor movement.
Console.is_interactive is set at construction time from is_terminal and not is_dumb_terminal, unless overridden by force_interactive or the TTY_INTERACTIVE environment variable.
Sources: rich/console.py862-960 rich/console.py736-748
| Variable | Effect |
|---|---|
NO_COLOR | Non-empty value disables all color output. Takes precedence over FORCE_COLOR. |
FORCE_COLOR | Non-empty value enables color regardless of TTY detection. |
TTY_COMPATIBLE | "1" forces terminal mode on; "0" forces it off. |
TTY_INTERACTIVE | "1" forces interactive mode on; "0" forces it off. |
TERM | "dumb" or "unknown" disables color and cursor-movement features. |
COLORTERM | "truecolor" or "24bit" selects ColorSystem.TRUECOLOR. |
COLUMNS | Sets console width when width is not provided to constructor. |
LINES | Sets console height when height is not provided to constructor. |
JUPYTER_COLUMNS | Sets width when in Jupyter and width not provided. Default: 115. |
JUPYTER_LINES | Sets height when in Jupyter and height not provided. Default: 100. |
UNICODE_VERSION | Controls cell-width calculation for multi-codepoint glyphs. |
Note: An empty string for NO_COLOR or FORCE_COLOR is treated as disabled (as of Rich 14.0).
Sources: rich/console.py663-748 docs/source/console.rst416-441
Console uses a threading.RLock stored as self._lock for all operations that modify shared state. Per-thread state (the output buffer and theme stack) is stored in ConsoleThreadLocals, which is a threading.local subclass rich/console.py541-548
Diagram: Thread-local vs shared state
Each thread gets its own buffer (a List[Segment]) and buffer_index. The shared _lock guards _record_buffer, _render_hooks, and _live_stack.
Sources: rich/console.py541-548 rich/console.py720-757 rich/console.py776-793
| Property | Type | Description |
|---|---|---|
file | IO[str] | The output file. Falls back through _file, stderr, stdout, or NULL_FILE. |
size | ConsoleDimensions | (width, height) from terminal or fixed values. |
width | int | Current console width in character cells. |
height | int | Current console height in lines. |
encoding | str | Encoding of the output file (e.g. "utf-8"). |
is_terminal | bool | Whether output goes to a real TTY. |
is_dumb_terminal | bool | Whether TERM=dumb or similar. |
is_interactive | bool | Whether animations (progress bars, status) should run. |
is_jupyter | bool | Whether rendering inside a Jupyter notebook. |
color_system | str | None | String representation of active color system. |
options | ConsoleOptions | Current ConsoleOptions snapshot, used by render methods. |
style | StyleType | None | Global style applied to all print output. |
no_color | bool | If True, colors are stripped from all output. |
Sources: rich/console.py762-875
ConsoleOptions is a dataclass that carries rendering parameters. It is passed to every __rich_console__ method. It is never constructed directly by user code; Console.options returns the current instance.
Sources: rich/console.py119-249
print(*objects, sep, end, style, justify, overflow, no_wrap, emoji, markup, highlight, width, height, crop, soft_wrap, new_line_start)The primary output method. Accepts any number of objects. Strings are processed for markup and highlighting; rich renderables (anything with __rich_console__) are rendered directly; plain objects are converted via __str__ and optionally highlighted.
Key parameters:
| Parameter | Default | Effect |
|---|---|---|
sep | " " | Separator between multiple objects |
end | "\n" | Appended after output |
style | None | Style applied to the entire print |
justify | None | "default", "left", "center", "right", "full" |
overflow | None | "fold", "crop", "ellipsis", "ignore" |
no_wrap | None | Disable word wrapping |
crop | True | Crop output to console width |
soft_wrap | False | Disable wrapping entirely (output overflows naturally) |
markup | None | Override console-level markup setting |
highlight | None | Override console-level highlight setting |
Sources: rich/console.py1624-1748
log(*objects, sep, end, style, justify, overflow, no_wrap, emoji, markup, highlight, log_locals, _stack_offset)Identical to print but prepends a timestamp and appends a caller file/line reference. The log_locals=True parameter causes a table of local variables at the call site to be rendered.
Sources: rich/console.py1750-1813
out(*objects, sep, end, style, highlight)A lower-level print. Does not apply markup or word-wrap. Converts all positional arguments to strings. Optionally applies a single style and runs the highlighter.
Sources: rich/console.py1604-1622
print_json(json, indent, highlight, skip_keys, ensure_ascii, check_circular, allow_nan, default, sort_keys)Renders a JSON string (or serializes data) with syntax highlighting using the JSON renderable.
Sources: rich/console.py1815-1853
rule(title, characters, style, align)Draws a horizontal rule across the full console width. The rule is optionally divided by a title. Delegates to the Rule renderable.
Sources: rich/console.py1856-1895
input(prompt, password, stream)Displays prompt using print(), then reads a line from stdin. If password=True, uses getpass to hide input.
Sources: rich/console.py1897-1929
status(status, spinner, spinner_style, speed, refresh_per_second)Returns a Status context manager that displays an animated spinner with a message alongside normal console output.
Sources: rich/console.py1931-1971
bell()Emits the terminal bell character (\x07) via Control.bell().
Sources: rich/console.py1973-1978
clear(home)Clears the terminal screen. If home=True (default), also moves the cursor to the top-left corner. Has no effect when not writing to a terminal.
Sources: rich/console.py1980-1997
control(*control)Writes Control objects directly to the output, bypassing the render pipeline. Used for cursor movement, screen mode switching, etc.
Sources: rich/console.py1999-2010
show_cursor(show)Shows or hides the terminal cursor by emitting the appropriate ANSI escape sequence.
Sources: rich/console.py2012-2022
capture()Returns a Capture context manager. Output produced within the context is redirected to an internal buffer instead of the terminal. Call Capture.get() after the context exits to retrieve the captured string.
with console.capture() as capture:
console.print("[bold red]Hello")
result = capture.get() # "Hello\n" (markup stripped)
Sources: rich/console.py2024-2038 rich/console.py316-346
pager(pager, styles, links)Returns a PagerContext context manager. Output is buffered and then passed to the system pager (or a custom Pager instance) on exit. By default, styles and links are stripped; pass styles=True to preserve ANSI codes.
Sources: rich/console.py2040-2075 rich/console.py370-407
use_theme(theme, inherit)Returns a ThemeContext context manager. The provided Theme is pushed onto the thread-local ThemeStack for the duration of the context.
Sources: rich/console.py2077-2093 rich/console.py349-368
screen(hide_cursor, style)Returns a ScreenContext context manager that activates the terminal's alternate screen mode. The cursor is hidden if hide_cursor=True. On exit, the alternate screen is deactivated.
Sources: rich/console.py2095-2118 rich/console.py409-453
All export methods require record=True at construction time.
| Method | Returns | Description |
|---|---|---|
export_text(clear, styles) | str | Plain text of recorded output |
export_html(theme, clear, code_format, inline_styles) | str | HTML document |
export_svg(title, theme, clear, unique_id, font_aspect_ratio, padding) | str | SVG document |
save_text(path, clear) | None | Writes text to file |
save_html(path, theme, clear, code_format, inline_styles) | None | Writes HTML to file |
save_svg(path, title, theme, clear, unique_id) | None | Writes SVG to file |
Sources: rich/console.py2120-2300
Console implements __enter__ and __exit__, which push and pop a buffer context. This means all output within the with block is buffered, and only flushed when the outermost context exits. Live and Pager use this mechanism internally.
Sources: rich/console.py863-870
RenderHook is an abstract base class with a single method process_renderables(renderables). Hooks are registered via push_render_hook() / pop_render_hook(). Before any batch of renderables is written to the output buffer, each registered hook is given the opportunity to inspect or replace the list. Live uses this mechanism to intercept console output during live display.
Sources: rich/console.py550-567 rich/console.py849-862
Diagram: Console print to terminal
Sources: rich/console.py1488-1574 rich/console.py1578-1602
console.pySeveral helper renderables are defined in rich/console.py itself rather than in separate modules:
| Class | Purpose |
|---|---|
NewLine | Yields Segment("\n" * count) |
ScreenUpdate | Renders a list of Segment lines at a given (x, y) position |
Group | Wraps multiple renderables into one; supports fit=True/False |
group | Decorator that converts a generator-of-renderables into a Group |
Sources: rich/console.py286-508
Sources: docs/source/console.rst1-441
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.