Skip to content

Getting Started

Python versions PyPI version PyPI downloads uv badge

Purpose

rich-gradient layers smooth foreground and background gradients on top of rich renderables. It includes a drop-in Text subclass, wrappers for Panel and Rule, utilities for building palettes, and a Click/rich-click CLI for trying gradients from the terminal.

Highlights

  • Works anywhere Rich expects a ConsoleRenderable, including panels, tables, and live updates.
  • Generates color stops automatically or from CSS color names, hex codes, RGB tuples, or rich.color.Color objects.
  • Supports foreground and background gradients, rainbow palettes, and deterministic color spectrums.
  • Ships with ready-to-use renderables:
Note

Includes a CLI rich-gradient for quick experiments and SVG export for documentation or asset generation.

Installation

uv (recommended)

uv add rich-gradient

or via uv pip

uv pip install rich-gradient


...or with pip:

pip

# via pip
pip install rich-gradient

Quick start

from rich.console import Console
from rich_gradient import Text

console = Console()
console.print(
    Text(
        "Rich gradients with almost no setup.",
        colors=["#38bdf8", "#a855f7", "#f97316"],
        style="bold",
        justify="center",
    )
)

The example above is bundled in examples/text_quickstart.py and renders:

Text quickstart

Explore the user guide

  • Text – gradient-aware drop-in replacement for rich.text.Text.
  • Gradient – wrap any renderable with foreground/background gradients.
  • Panel – gradient panels with highlighted titles and subtitles.
  • Rule – gradient horizontal rules with adjustable thickness.
  • Spectrum – generate and preview deterministic palettes.
  • CLI – scriptable demos and helpers built with Click + rich-click.
  • Animation – create animated gradients with Live.

Latest (v0.3.9)

  • CLI docs and examples reflect the Click + rich-click commands (print, panel, rule, markdown) with current options.
  • Help text uses consistent rich markup styling across commands.
  • Tests run without an editable install via the tests/conftest.py path shim.
  • Docs background now respects the theme, removing the black/transparent flash on initial paint.

Prefer API-level details? See the reference section generated with mkdocstrings.