This page documents Rich's platform detection and adaptation mechanisms. Rich automatically detects the environment it's running in and adapts its output to provide consistent functionality across all platforms.
Rich's platform support spans three major areas:
| Area | Key Files | Purpose |
|---|---|---|
| Windows Legacy Console | rich/_win32_console.py, rich/_windows.py, rich/_windows_renderer.py | Direct Win32 API calls for terminals without VT processing |
| Jupyter Rendering | rich/jupyter.py | HTML-based rendering in Jupyter/IPython environments |
| Unicode Cell Widths | rich/cells.py, rich/_unicode_data/ | Accurate terminal width measurement for all Unicode text |
Rich detects and adapts to:
Detection happens automatically during Console initialization and can be overridden via constructor arguments or environment variables.
Console Initialization Platform Detection Flow
The force_terminal, force_jupyter, and force_interactive constructor arguments allow explicit overrides of auto-detection.
Rich detects Jupyter notebooks and similar IPython environments (including Google Colab and Databricks) to provide HTML-based output instead of ANSI escape sequences.
Jupyter detection checks for the presence of get_ipython in the global namespace. The detected shell class name determines whether Rich switches to Jupyter mode:
ZMQInteractiveShell → Jupyter notebook or qtconsolegoogle.colab in the class path → Google ColabDATABRICKS_RUNTIME_VERSION environment variable → DatabricksTerminalInteractiveShell → plain IPython terminal (not Jupyter)When running in Jupyter, Console uses:
| Feature | Terminal | Jupyter |
|---|---|---|
| Default Width | Auto-detect or 80 | 115 (or JUPYTER_COLUMNS env var) |
| Default Height | Auto-detect or 25 | 100 (or JUPYTER_LINES env var) |
| Color System | Auto-detect | TRUECOLOR |
| Progress Bars | Live ANSI updates | Static HTML snapshots |
| Legacy Windows | Possible | Never |
rich/jupyter.py provides the infrastructure for rendering Rich output in Jupyter environments.
Class hierarchy and relationships
Sources: rich/jupyter.py18-56
JupyterMixinAdd JupyterMixin as a base class to any Rich renderable to make it directly displayable in Jupyter without a Console. It implements _repr_mimebundle_, which Jupyter calls when displaying an object.
When _repr_mimebundle_ is called, JupyterMixin:
Console via get_console()self through console.render() to produce Segment objects_render_segments()text/plain and text/html MIME typesJupyterRenderableA lightweight wrapper holding pre-rendered HTML and plain text. Returned by display() and passed to IPython.display.display().
_render_segments()Converts an iterable of Segment objects to an HTML string. Control segments are skipped. Text styles are converted to CSS using Style.get_html_style() against the DEFAULT_TERMINAL_THEME.
The output is wrapped in:
<pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">{code}</pre>
display()Renders a buffer of Segment objects to Jupyter by creating a JupyterRenderable and calling IPython.display.display(). If IPython is not installed, the call is silently ignored.
Jupyter rendering data flow
Sources: rich/jupyter.py36-96
Rich detects the capabilities of Windows terminals to determine the appropriate rendering approach:
ENABLE_VIRTUAL_TERMINAL_PROCESSING flag).WindowsConsoleFeatures and get_windows_console_features()rich/_windows.py defines the WindowsConsoleFeatures dataclass and the get_windows_console_features() function:
get_windows_console_features() calls GetStdHandle() and GetConsoleMode() from rich/_win32_console.py. If GetConsoleMode raises LegacyWindowsError, both vt and truecolor are set to False. TrueColor is only enabled when VT is active and the Windows build is ≥ 15063.
If the Windows DLLs cannot be loaded (e.g., on non-Windows platforms), the module provides a fallback get_windows_console_features() that always returns WindowsConsoleFeatures(vt=False, truecolor=False).
Sources: rich/_windows.py1-61
For Windows terminals that do not support VT processing, Rich provides an alternative rendering path using direct Win32 API calls via LegacyWindowsTerm and legacy_windows_render().
Legacy Windows rendering architecture
Sources: rich/_win32_console.py331-572 rich/_windows_renderer.py1-57
LegacyWindowsTermDefined in rich/_win32_console.py. Only importable on Windows (sys.platform == "win32"). It wraps the Win32 Console API via ctypes.
On construction it calls GetStdHandle(STDOUT) and GetConsoleScreenBufferInfo() to record the default text attributes (used to reset styling after each styled write).
Key methods:
| Method | Win32 API Used |
|---|---|
write_text(text) | file.write() + flush() |
write_styled(text, style) | SetConsoleTextAttribute() + write_text() |
move_cursor_to(coords) | SetConsoleCursorPosition() |
erase_line() | FillConsoleOutputCharacter() + FillConsoleOutputAttribute() |
erase_end_of_line() | FillConsoleOutputCharacter() + FillConsoleOutputAttribute() |
erase_start_of_line() | FillConsoleOutputCharacter() + FillConsoleOutputAttribute() |
hide_cursor() | SetConsoleCursorInfo() |
show_cursor() | SetConsoleCursorInfo() |
set_title(title) | SetConsoleTitleW() |
Sources: rich/_win32_console.py331-572
rich/_win32_console.py exposes thin ctypes wrappers around the following Win32 functions. All wrappers are only available when sys.platform == "win32":
| Python wrapper | Win32 function |
|---|---|
GetStdHandle() | kernel32.GetStdHandle |
GetConsoleMode() | kernel32.GetConsoleMode |
GetConsoleScreenBufferInfo() | kernel32.GetConsoleScreenBufferInfo |
SetConsoleTextAttribute() | kernel32.SetConsoleTextAttribute |
SetConsoleCursorPosition() | kernel32.SetConsoleCursorPosition |
GetConsoleCursorInfo() | kernel32.GetConsoleCursorInfo |
SetConsoleCursorInfo() | kernel32.SetConsoleCursorInfo |
FillConsoleOutputCharacter() | kernel32.FillConsoleOutputCharacterW |
FillConsoleOutputAttribute() | kernel32.FillConsoleOutputAttribute |
SetConsoleTitle() | kernel32.SetConsoleTitleW |
Sources: rich/_win32_console.py71-328
Rich maps ANSI colors to Windows Console colors using a specific mapping table:
| ANSI Color | Windows Color Code |
|---|---|
| Black (0) | 0 |
| Red (1) | 4 |
| Green (2) | 2 |
| Yellow (3) | 6 |
| Blue (4) | 1 |
| Magenta (5) | 5 |
| Cyan (6) | 3 |
| White (7) | 7 |
| Bright Black (8) | 8 |
| Bright Red (9) | 12 |
| Bright Green (10) | 10 |
| Bright Yellow (11) | 14 |
| Bright Blue (12) | 9 |
| Bright Magenta (13) | 13 |
| Bright Cyan (14) | 11 |
| Bright White (15) | 15 |
This mapping ensures consistent color display between ANSI-based terminals and the Windows Console.
Sources: rich/_win32_console.py343-360
legacy_windows_render() in rich/_windows_renderer.py iterates over a buffer of Segment objects and dispatches to LegacyWindowsTerm:
Sources: rich/_windows_renderer.py7-57
The legacy_windows_render() function maps Rich's control codes to Windows Console API calls:
| Control Code | Windows Console API Function |
|---|---|
| CURSOR_MOVE_TO | move_cursor_to() |
| CARRIAGE_RETURN | write_text("\r") |
| HOME | move_cursor_to(0, 0) |
| CURSOR_UP | move_cursor_up() |
| CURSOR_DOWN | move_cursor_down() |
| CURSOR_FORWARD | move_cursor_forward() |
| CURSOR_BACKWARD | move_cursor_backward() |
| CURSOR_MOVE_TO_COLUMN | move_cursor_to_column() |
| HIDE_CURSOR | hide_cursor() |
| SHOW_CURSOR | show_cursor() |
| ERASE_IN_LINE (mode 0) | erase_end_of_line() |
| ERASE_IN_LINE (mode 1) | erase_start_of_line() |
| ERASE_IN_LINE (mode 2) | erase_line() |
| SET_WINDOW_TITLE | set_title() |
Sources: rich/_windows_renderer.py14-56
Rich handles the difference between the zero-based coordinates used by the Windows Console API and the one-based coordinates used in ANSI escape sequences:
The WindowsCoordinates class encapsulates the row and column position in the console, and provides a conversion method to the Win32 API's COORD structure. This class manages the mapping between the different coordinate systems.
Sources: rich/_win32_console.py33-54
The Console class automatically detects Windows platform features and selects the appropriate rendering method:
This abstraction allows Rich users to write platform-agnostic code while still getting optimal rendering on all platforms.
Sources: rich/_windows.py38-61
Legacy Windows consoles have several limitations compared to modern terminals:
Rich handles these limitations by:
Sources: rich/_win32_console.py405-442
Rich ensures proper Unicode support across all Windows terminal types, handling differences in how modern and legacy Windows consoles display non-ASCII characters.
Sources: rich/_win32_console.py396-403
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.