Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Rich: Markdown, JSON, and Layouts in the Terminal

Combine Python Rich's Markdown, JSON, and Layout renderables to build readable CLI output with syntax highlighting and responsive panels.

~5 min readPython
#Rich#Terminal UI#Markdown#JSON
Terminal window showing Markdown, JSON, and layout panels rendered with Python Rich

Python command-line tools often need to present more than plain text: API responses, documentation snippets, and dashboard-style panels all benefit from readable formatting in the terminal. Rich provides Markdown, JSON, and Layout renderables for exactly these situations, so you can combine them into one organized CLI view.

What Rich Provides for Terminal Output

Rich is a Python library that adds colors, styles, tables, panels, and more to terminal output. Instead of manually inserting ANSI escape codes, you use high-level objects that Rich renders for you. Three of its most useful components for data-heavy CLIs are Markdown, JSON, and Layout. Markdown renders formatted text with headings, emphasis, and code blocks. JSON displays JSON data with syntax highlighting and indentation. Layout divides the terminal into resizable regions that can each contain different Rich renderables.

These components work together. You can put a Markdown document in one panel and a JSON payload in another, then arrange them side by side or stacked. The result is a terminal interface that feels like a lightweight GUI without leaving the command line.

Rendering Markdown with Rich

The rich.markdown.Markdown class takes a string containing Markdown and renders it with proper formatting. You pass it to Console.print() like any other renderable. Here is a minimal example:

python
from rich.console import Console from rich.markdown import Markdown console = Console() markdown_text = """ # Project Status **Updated:** 2024-11-05 ## Highlights - API rate limit increased - New endpoint for batch processing """ console.print(Markdown(markdown_text))

Rich parses the Markdown and applies styles: headings are bold and colored, emphasis is italic, and inline code gets a background. It also handles links and images, though images are shown as text placeholders in the terminal. The Markdown object accepts options like code_theme to control syntax highlighting of fenced code blocks within the Markdown.

For dynamic content, you can create a new Markdown instance whenever the text changes. This is useful when you are rendering log output or documentation that updates in real time.

Displaying JSON with Rich

The rich.json.JSON class renders JSON with syntax highlighting and proper indentation. You can pass a JSON string directly, or use a dictionary and let Rich serialize it. Here is an example:

python
from rich.console import Console from rich.json import JSON console = Console() data = { "user": "alice", "roles": ["admin", "editor"], "last_login": "2024-11-05T10:30:00Z" } console.print(JSON.from_data(data))

JSON.from_data() is a class method that accepts a Python object and converts it to a JSON string internally. Alternatively, you can pass a raw JSON string to JSON(json_string). Rich colors keys, strings, numbers, and booleans differently, making it easy to spot structural issues at a glance.

When you have large JSON payloads, you can control the indentation with the indent parameter and enable or disable highlight. For example, JSON(json_str, indent=4) produces more readable output. If you pass a malformed JSON string, Rich raises a JSONDecodeError; catch it when handling input from untrusted sources.

Building Responsive Layouts with Rich

The rich.layout.Layout class lets you split the terminal into rows and columns. You define a layout tree, then assign renderables to each leaf. The layout automatically resizes when the terminal window changes. Here is a basic two-column layout:

python
from rich.console import Console from rich.layout import Layout from rich.panel import Panel from rich.markdown import Markdown from rich.json import JSON console = Console() layout = Layout() layout.split_row( Layout(name="left"), Layout(name="right") ) markdown = Markdown("# Docs\n\nThis is the left panel.") json_data = JSON.from_data({"status": "ok", "count": 42}) layout["left"].update(Panel(markdown, title="Documentation")) layout["right"].update(Panel(json_data, title="Response")) console.print(layout)

The split_row method creates side-by-side panels. You can also use split_column for vertical stacking, or nest them to create complex grids. Each Layout has a size attribute to set a fixed width or height, and a ratio to control proportional sizing. For example, Layout(name="left", ratio=2) makes the left panel twice as wide as the right when both have ratio=1.

Layouts are not limited to panels; you can put any Rich renderable inside, including tables, text, or even other layouts. This makes them ideal for dashboards that combine multiple data sources.

Combining Markdown, JSON, and Layouts in One View

A common pattern in CLI tools is to show a help document alongside the JSON response from an API. You can achieve this by placing a Markdown object in one layout region and a JSON object in another. The following example builds a three-region layout: a header, a left column with Markdown, and a right column with JSON.

python
from rich.console import Console from rich.layout import Layout from rich.panel import Panel from rich.markdown import Markdown from rich.json import JSON console = Console() layout = Layout() layout.split_column( Layout(name="header", size=3), Layout(name="body") ) layout["body"].split_row( Layout(name="docs", ratio=2), Layout(name="data", ratio=1) ) header = Panel("API Console", style="bold blue") markdown = Markdown("# Usage\n\nCall `GET /v1/users` to list users.") json_data = JSON.from_data({"users": [{"id": 1, "name": "Alice"}]}) layout["header"].update(header) layout["docs"].update(Panel(markdown, title="Docs")) layout["data"].update(Panel(json_data, title="JSON Response")) console.print(layout)

When you run this, the terminal shows a header panel at the top, with the Markdown on the left and the JSON on the right. The layout reflows automatically if you resize the terminal, so the content remains readable. You can update any region later by calling update() again with a new renderable, which is useful for interactive applications that refresh periodically.

One thing to keep in mind is that Layout does not handle scrolling internally. If a panel's content exceeds the available space, Rich clips it. For long documents, plan accordingly: limit the content you render, or use an external pager such as less. Console.print has a soft_wrap option for controlling line wrapping, but it does not add scrolling to a layout.

Performance and Output Size Considerations

Rich adds a parsing and styling layer on top of plain text output. For small Markdown strings and JSON objects, the overhead is negligible. But when you render a multi-megabyte JSON file or a very long Markdown document, the initial parsing can take noticeable time and produce a large amount of ANSI escape codes, which slows down terminal rendering.

If you are dealing with large data, you have a few options. For JSON, you can use the indent parameter sparingly or set highlight=False to reduce styling work. For Markdown, you can limit the input size before passing it to Rich. Alternatively, you can use Rich's Console.capture() to test the output size and decide whether to truncate.

Another consideration is non-TTY environments. When you pipe your script's output to a file or another command, Rich automatically disables colors and styles if the output is not a terminal. This is controlled by the force_terminal and no_color options on Console. If you want to force plain text output, you can create a Console(force_terminal=False).

Choosing Between Rich and Plain Text Output

Rich is not always the right choice. If you are writing a script that will be used in automated pipelines where output is parsed by other tools, plain text or JSON is more appropriate. Rich's styled output is meant for human eyes, not for machine consumption. For example, a curl-like tool that outputs JSON for scripting should not use Rich's JSON renderer; it should print raw JSON.

Use Rich when you are building an interactive CLI, a development tool, or a diagnostic utility where the user is looking at the terminal directly. The combination of Markdown, JSON, and layouts gives you a way to present complex information without requiring a GUI. Just be aware of the performance tradeoff and the fact that the output is not easily parseable by other programs.

If you need to support both human and machine-readable output, you can add a --json flag to your CLI that prints raw JSON, while the default output uses Rich. This gives you the best of both worlds: a pleasant experience for interactive use and a stable format for automation.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.