Async Click

8.3.0.7 · active · verified Sat Apr 11

Asyncclick is a fork of Click that works seamlessly with Trio or asyncio, enabling the use of asynchronous command and subcommand handlers for building composable command line interfaces. It aims to provide the familiar Click API with added async capabilities. The current version is 8.3.0.7, released on October 11, 2025, and generally follows the upstream Click project's release cadence.

Warnings

breaking `asyncclick.prompt` is now asynchronous and must be awaited. It also introduces a `blocking` parameter.
Fix: Ensure all calls to `asyncclick.prompt` are prefixed with `await`. Consider the `blocking` parameter if dealing with interrupt handling.
breaking `Context.exit` has been renamed to `Context.aexit` and is now an asynchronous method.
Fix: Replace `Context.exit` calls with `await Context.aexit` to correctly handle asynchronous teardown callbacks and context managers.
gotcha Do not mix direct imports from the synchronous `click` library and `asyncclick` in the same program.
Fix: Replace `import click` with `import asyncclick as click` and ensure all decorators and functions (`command`, `option`, `group`, `echo`, etc.) are imported from `asyncclick`.
gotcha Performing blocking synchronous I/O or CPU-bound operations directly in `async` command handlers will block the event loop, negating the benefits of async programming.
Fix: For CPU-bound tasks, use `anyio.to_thread.run_sync()` or `asyncio.to_thread()` (or `loop.run_in_executor` for older `asyncio`) to offload work to a thread pool. For blocking I/O, use async-native libraries (e.g., `aiohttp` instead of `requests`).
deprecated Asyncclick inherits deprecations from upstream Click. For example, `BaseCommand` and `MultiCommand` are deprecated in favor of `Command` and `Group` respectively, and the `__version__` attribute is deprecated in favor of `importlib.metadata.version("click")`.
Fix: Consult the Click 8.x changelog for specific deprecations. Prefer using `Command` and `Group` for base classes and `importlib.metadata.version` for version retrieval.

Install

pip install asyncclick Install stable version

Imports

command
```
from asyncclick import command
```
Asyncclick replaces the standard Click imports for async functionality. Do not mix imports from `click` and `asyncclick` in the same program.
group
```
from asyncclick import group
```
Asyncclick replaces the standard Click imports for async functionality. Do not mix imports from `click` and `asyncclick` in the same program.
option
```
from asyncclick import option
```
Asyncclick replaces the standard Click imports for async functionality. Do not mix imports from `click` and `asyncclick` in the same program.
echo
```
from asyncclick import echo
```
Asyncclick replaces the standard Click imports for async functionality. Do not mix imports from `click` and `asyncclick` in the same program.
click (alias)
```
import asyncclick as click
```
When migrating from Click, replace `import click` with `import asyncclick as click` to seamlessly use async-enabled handlers. Mixing direct imports is not supported.

Quickstart

This quickstart demonstrates a basic asynchronous command using `asyncclick`. It defines a command with options and arguments, and includes an `await` call to simulate an asynchronous operation, showcasing `asyncclick`'s core functionality.

import asyncclick as click
import anyio

@click.command()
@click.option("--count", default=1, help="Number of greetings.")
@click.option("--name", prompt="Your name", help="The person to greet.")
async def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for _ in range(count):
        click.echo(f"Hello, {name}!")
        await anyio.sleep(0.1) # Simulate async I/O

if __name__ == '__main__':
    # asyncclick automatically starts an anyio event loop
    # and runs your code asynchronously.
    hello()

view raw JSON →