Click REPL Plugin

0.3.0 verified Tue May 12 auth: no python install: verified quickstart: stale

click-repl is a Python library that provides a REPL (Read-Eval-Print Loop) plugin for Click-based command-line applications. It allows users to execute multiple commands in a single interactive session, maintaining a shared context. The current version is 0.3.0, released in June 2023, and it generally follows the release cadence of its upstream dependency, Click.

pip install click-repl

Common errors

error ModuleNotFoundError: No module named 'click._bashcomplete' ↓

cause This error occurs because older versions of `click-repl` (prior to 0.2.0) depended on an internal `click._bashcomplete` module, which was removed in Click version 8.0.0.

fix

Upgrade click-repl to version 0.2.0 or newer using pip install --upgrade click-repl. Alternatively, downgrade Click to a version below 8.0.0 using pip install "click<8.0.0".

error AttributeError: 'Command' object has no attribute 'commands' ↓

cause The `repl` function (or `register_repl`) expects a `click.Group` object or the context of a `Group` to provide available commands, but it received a `click.Command` object instead.

fix

Ensure that register_repl() or repl() is called with a click.Group instance (e.g., register_repl(cli) where cli is a click.Group) or the context of a group, not a simple click.Command.

error Unhandled UsageError exception when unsupported command is provided ↓

cause When an unknown command is entered in the `click-repl` session, the underlying `click.UsageError` is not always caught and handled gracefully, leading to a traceback.

fix

Upgrade click-repl to the latest version to ensure bug fixes related to exception handling are applied. For example: pip install --upgrade click-repl.

error ModuleNotFoundError: No module named 'click' ↓

cause The `click` library, which `click-repl` depends on, is not installed in the current Python environment.

fix

Install the click package using pip: pip install click.

Warnings

breaking `click-repl` 0.3.0 dropped support for Python 2.x. Applications running on Python 2 must use an older version (e.g., 0.2.x). ↓

fix Upgrade to Python 3.6+ or pin `click-repl` to a version compatible with Python 2.x (e.g., `click-repl<0.3.0`).

breaking In `click-repl` 0.3.0, the internal implementation for the `prompt()` function was changed to use `prompt_toolkit.PromptSession()` instead of `prompt_toolkit.prompt()`. While this fixed an unbound memory usage growth, it might subtly affect highly customized REPL environments that were directly interacting with the internal prompt mechanism. ↓

fix Review custom REPL implementations, especially if directly manipulating `prompt_toolkit` internals, to ensure compatibility with `PromptSession`.

gotcha Older versions of `click-repl` (specifically prior to 0.2.0) were incompatible with Click 8.0.0 due to changes in Click's internal API. Attempting to use `click-repl` 0.1.x with Click 8+ will result in import errors or runtime failures. ↓

fix Ensure `click-repl` is version 0.2.0 or higher when using Click 8.x or newer. The current version (0.3.0) is compatible.

gotcha When using `click-repl`, the parent context (`ctx.obj`) is reused between subcommands. This is a feature for performance but can be a footgun if you expect a fresh context for each REPL command, potentially leading to stale data or unexpected side effects if not handled carefully. ↓

fix Be mindful of state stored in `ctx.obj` within the REPL. Explicitly clear or reset relevant data if a fresh state is required for subsequent commands.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.51s 22.6M

3.10 alpine (musl) - - 0.49s 22.5M

3.10 slim (glibc) wheel 1.9s 0.38s 23M

3.10 slim (glibc) - - 0.33s 23M

3.11 alpine (musl) wheel - 0.65s 25.2M

3.11 alpine (musl) - - 0.69s 25.0M

3.11 slim (glibc) wheel 2.1s 0.57s 26M

3.11 slim (glibc) - - 0.50s 26M

3.12 alpine (musl) wheel - 0.85s 16.8M

3.12 alpine (musl) - - 0.81s 16.7M

3.12 slim (glibc) wheel 1.8s 0.77s 17M

3.12 slim (glibc) - - 0.76s 17M

3.13 alpine (musl) wheel - 0.86s 16.6M

3.13 alpine (musl) - - 0.80s 16.3M

3.13 slim (glibc) wheel 1.9s 0.77s 17M

3.13 slim (glibc) - - 0.77s 17M

3.9 alpine (musl) wheel - 0.51s 21.9M

3.9 alpine (musl) - - 0.50s 21.8M

3.9 slim (glibc) wheel 2.2s 0.44s 22M

3.9 slim (glibc) - - 0.39s 22M

Imports

register_repl
```
from click_repl import register_repl
```
repl
```
from click_repl import repl
```
Used for advanced REPL customization, instead of `register_repl`.

Quickstart stale last tested: 2026-04-24

This quickstart demonstrates how to integrate `click-repl` into a basic Click application. It defines a Click group `cli` with two commands, `hello` and `greet`. The `register_repl(cli)` function adds a 'repl' subcommand to the CLI, enabling an interactive session where `hello` and `greet` can be executed. To run, save as `my_app.py` and execute `python my_app.py repl` in your terminal, then type `hello` or `greet yourname`.

import click
from click_repl import register_repl

@click.group()
def cli():
    """A simple CLI with a REPL."""
    pass

@cli.command()
def hello():
    click.echo("Hello from the REPL!")

@cli.command()
@click.argument('name')
def greet(name):
    click.echo(f"Nice to meet you, {name}!")

if __name__ == '__main__':
    register_repl(cli)
    cli()