Installation¶
Quick start¶
Click Extra is distributed on PyPI.
So you can install the latest stable release with your favorite package manager like uv:
$ uv pip install click-extra
Demo CLI¶
You can try Click Extra right now in your terminal, without installing any dependency or virtual env thanks to uvx. This downloads and runs click-extra, a demo CLI included in the package:
$ uvx click-extra
$ click-extra --help
Usage: click-extra [OPTIONS] COMMAND [ARGS]...
Click Extra CLI.
Options:
-h, --help Show this message and exit.
Configuration options:
--config LOCATION Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/click-extra/]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config LOCATION Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
Output options:
--accessible Accessibility mode: disable colors and render
tables in a borderless, screen-reader-friendly
format.
--color [auto|always|never] Colorize the output. A bare --color is the same
as --color=always. [default: auto]
--no-color Disable colorization (alias of --color=never).
--progress / --no-progress Show progress indicators during long operations.
Disabled for non-interactive output (pipes, dumb
terminals, CI) and by --accessible. [default:
progress]
--theme [auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
Color theme used for help screens. [default:
dark]
--table-format FORMAT Rendering style of tables. [default: rounded-
outline]
Logging options:
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
-q, --quiet Decrease the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
--debug Shorthand for --verbosity DEBUG.
Introspection options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--tree Show the tree of nested subcommands and exit.
--man Read the command's manual page and exit.
--help-format [carapace|json|json-full|man|markdown|markdown-full]
Render the command in the given format and exit.
--version Show the version and exit.
Demo:
8color Render all standard 8-color foreground/background...
colors Render every foreground color against every background...
gradient Render 24-bit RGB gradients beside their 256-color...
palette Render a compact 256-color indexed swatch.
spinner Animate the spinner widget; --table lists the catalog...
styles Render every color with each text style (bold, dim,...
themes Render a sample help screen under each theme, one after...
trail Trace a simulated batch of operations behind an...
Other commands:
convert-to-myst Convert reST docstrings to MyST markdown in Python...
help Show help for a command.
prebake Pre-bake build-time metadata into Python source files.
refresh-directives Refresh the self-updating blocks embedded in Markdown...
screenshot Capture a command's colored output and write it as an...
snippet Highlight a source file and write it as an image or HTML.
test-suite Run declarative CLI test cases against a command or...
wrap (run) Run, or introspect, any Click CLI through Click Extra.
Examples:
Run any Click CLI through Click Extra's colored help:
$ click-extra wrap -- my-cli --help
Draw that help screen as a picture a README can show:
$ click-extra screenshot --output my-cli.svg -- my-cli --help
Report the parameters a CLI accepts, and where each value comes from:
$ click-extra wrap --params -- my-cli
Highlight a source file as a themed picture:
$ click-extra snippet --output basket.svg basket.py
See how a help screen reads under each built-in theme:
$ click-extra themes
$ uvx click-extra@10.2.0
$ uvx --from git+https://github.com/kdeldycke/click-extra -- click-extra
$ uvx --from file:///Users/me/code/click-extra -- click-extra
The demo CLI showcases various features of Click Extra, such as enhanced help formatting, colored output, and more. The help screen in the Latest release tab is rendered at build time, so it always matches the current code. The CLI reference documents every command with its live help screen.
And so you can explore the various possibilities of the demo application, like showing the current version:
$ uvx click-extra --version
This is a great way to play with Click Extra and check that it runs fine on your system, and renders properly in your terminal.
The demo CLI is also compiled into standalone executables for Linux, macOS, and Windows, so you can try it without Python or uv.
Try the library¶
Now that you have tried the demo application, you can also try the library itself in an interactive Python shell without installing anything on your system:
$ uvx --with click-extra python
Installed 8 packages in 5ms
Python 3.14.0 free-threading build (main, Oct 28 2025, 11:52:40) [Clang 20.1.4 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from click_extra import echo, style
>>> echo(style("Hello, World!", fg="green"))
Hello, World!
>>>
Installation methods¶
Easiest way is to install uv, then add click-extra to your project:
$ uv add click-extra
Or to install the demo CLI system-wide with uv tool:
$ uv tool install click-extra
You can install the latest stable release and its dependencies with a simple pip call:
$ python -m pip install click-extra
If you have difficulties to use pip, see
pip’s own installation instructions.
pipx is a great way to install the demo CLI globally:
$ pipx install click-extra
Arch Linux users install python-click-extra from the AUR, with the helper of their choice:
$ paru -S python-click-extra
The package needs python-click 8.5.1 or newer.
GNU Guix users install python-click-extra with guix install:
$ guix install python-click-extra
MacPorts splits py-click-extra into one port per Python version, like py313-click-extra for Python 3.13. Install the one matching your Python with port install:
$ sudo port install py313-click-extra
openSUSE Tumbleweed ships one package per Python version, like python313-click-extra for Python 3.13. Install it with zypper:
$ sudo zypper install python313-click-extra
Support envelope¶
Each compatibility table below keeps the support envelope of its own axis. Across the three tables, these are obsolete, even where a table still shows them:
click-extrareleases before8.0.0(2026-06-22)Python versions before
3.10(2021-10-04)clickversions before8.3.1(2025-11-15)cloupversions before3.0.7(2025-03-15)
Python compatibility¶
Each cell holds one of three states:
✅: the release declares support for that Python.
❌: the
requires-pythonof the release rules that Python out.–: the release neither claimed nor forbade that Python, usually because that Python was not out yet when the release declared its requirements.
See three states, two sources. The table keeps the support envelope of its axis, so the oldest releases drop off as the oldest Python the latest release supports moves up.
|
|
|
|
|
|
|
|
|
|
|---|---|---|---|---|---|---|---|---|---|
|
✅ |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
❌ |
❌ |
|
✅ |
✅ |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
❌ |
|
– |
✅ |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
❌ |
|
– |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
❌ |
❌ |
|
– |
– |
✅ |
✅ |
✅ |
❌ |
❌ |
❌ |
❌ |
|
– |
– |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
❌ |
|
– |
– |
– |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
|
– |
– |
– |
✅ |
✅ |
✅ |
✅ |
✅ |
❌ |
|
– |
– |
– |
– |
✅ |
✅ |
✅ |
✅ |
✅ |
Click compatibility¶
Click Extra wraps Click, so the two are tightly coupled and the matrix of supported Click versions matters as much as the Python one.
|
|
|
|
|
|---|---|---|---|---|
|
✅ |
✅ |
❌ |
❌ |
|
– |
✅ |
✅ |
❌ |
|
– |
✅ |
✅ |
✅ |
Cloup compatibility¶
Click Extra’s commands and groups subclass those of Cloup, which subclass Click’s, and its option groups extend Cloup’s. Cloup is therefore the other dependency whose supported range matters.
|
|
|
|---|---|---|
|
✅ |
❌ |
|
✅ |
✅ |
Binaries¶
Standalone executables of the demo CLI’s latest release are available as direct downloads for several platforms and architectures:
Platform ↴ \ Architecture → |
|
|
|---|---|---|
Linux |
||
macOS |
||
Windows |
Binaries of all past releases, with their VirusTotal analyses, are cataloged on the binaries page.
Release verification¶
Every binary is signed with a build provenance attestation at release time. After downloading one, verify it with the gh CLI:
$ gh attestation verify click-extra-linux-x64.bin --repo kdeldycke/click-extra --signer-repo kdeldycke/repomatic
--signer-repo kdeldycke/repomatic is required because the release runs from repomatic’s reusable release workflow, whose signing identity is kdeldycke/repomatic.
The PyPI distributions carry their own PEP 740 attestations, visible and verifiable on the PyPI project page.
Man pages¶
The demo CLI has a --man option, which typesets its manual and pages it, the way man does:
$ click-extra --man
To get the roff source instead, ask for the man rendering of --help-format:
$ click-extra --help-format man
The full command tree is also pre-rendered as static .1 files:
Bundled with the latest release as
click-extra-manpages.tar.gz. Extract it, then copy the.1files of itsman/folder to${MANPATH%%:*}/man1/(typically/usr/local/share/man/man1/).Rendered as HTML pages on the documentation site, listed in the man page index.
Packagers can regenerate them from source as part of their build phase:
$ click-extra wrap --help-format man --output-dir /usr/share/man/man1/ -- click_extra.cli:demo
The generator honors SOURCE_DATE_EPOCH for reproducible builds. See shipping a manual for the other invocation forms.
Extra dependencies¶
By default, Click Extra reads the configuration formats enabled by default and renders all standard table formats. Optional extras unlock additional features:
Extra |
Install command |
Unlocks |
|---|---|---|
|
$ uv pip install 'click-extra[hjson]'
|
|
|
$ uv pip install 'click-extra[json5]'
|
|
|
$ uv pip install 'click-extra[toml]'
|
|
|
$ uv pip install 'click-extra[yaml]'
|
|
|
$ uv pip install 'click-extra[carapace]'
|
|
|
$ uv pip install 'click-extra[mkdocs]'
|
|
|
$ uv pip install 'click-extra[pygments]'
|
|
|
$ uv pip install 'click-extra[sphinx]'
|
|
|
$ uv pip install 'click-extra[pytest]'
|
|
Tip
Install all extras at once with:
$ uv pip install 'click-extra[all]'