Docket

0.18.2 verified Tue May 12 auth: no python install: stale

Docket is a Python library that provides a distributed background task system for executing Python functions. It is currently at version 0.18.2 and maintains an active development cycle with frequent releases, offering robust solutions for task scheduling and execution.

pip install docket

Common errors

error ModuleNotFoundError: No module named 'docket' ↓

cause The Python package for the 'docket' library is published under the name 'pydocket' on PyPI, not 'docket'.

fix

Install the correct package: pip install pydocket or uv pip install pydocket.

error redis.exceptions.ConnectionError: Error 111 connecting to 127.0.0.1:6379. Connection refused. ↓

cause The `docket` library requires a running Redis server with Streams support, and this error indicates the client cannot connect to it.

fix

Ensure a Redis server (version 5.0.0 or higher) is running and accessible at the specified host and port, and that no firewall is blocking the connection. You can also specify the Redis URL when initializing Docket: Docket(url="redis://your_redis_host:port").

error AttributeError: 'function' object has no attribute 'delay' ↓

cause Unlike some other background task libraries (e.g., Celery), `docket` does not use a `.delay()` method on task functions. Tasks are plain async functions scheduled using `docket.add()`.

fix

Schedule tasks using the docket.add() method: await docket.add(your_async_task)(arg1, arg2) instead of your_async_task.delay(arg1, arg2).

error Tasks are not being processed by the worker. ↓

cause Docket workers need to be explicitly registered with the tasks they are expected to process. If tasks are not registered, the worker won't know about them and will not execute them.

fix

Register your task functions with the worker using worker.register(your_task_function) or pass a collection of tasks via CLI: docket worker --tasks your_module:your_task_collection.

Warnings

breaking From version 0.18.0, Docket's internal dependency system was extracted into the `uncalled-for` library. While intended to be a transparent change for most users, deep or custom integrations with Docket's dependency resolution might require review. ↓

fix No direct code changes are typically required, as `uncalled-for` is installed as a dependency of `docket`. However, if experiencing issues, ensure `uncalled-for` is correctly installed and consult its documentation if custom dependency injection logic was previously implemented.

gotcha Docket tasks are fundamentally asynchronous (`async def`) and rely on `asyncio`. Incorrectly mixing synchronous code in an async task, or blocking the event loop, can lead to performance issues or deadlocks. ↓

fix Ensure all I/O-bound or long-running operations within tasks are non-blocking or are offloaded to an executor (e.g., `loop.run_in_executor`) to prevent blocking the `asyncio` event loop. Always `await` asynchronous calls.

gotcha When using `Cron` dependencies for task scheduling, ensure careful consideration of timezones. Default behavior might rely on the system's local timezone, which can lead to unexpected execution times in distributed or timezone-aware applications. ↓

fix Explicitly specify the timezone using the `tz` argument in the `Cron` constructor (e.g., `Cron('0 0 * * *', tz='America/New_York')`). Verify that your system's timezone settings are consistent across all Docket worker nodes.

gotcha Using persistent backends (e.g., Redis, PostgreSQL) requires robust configuration and connection management to ensure tasks are reliably stored, retrieved, and processed across application restarts and distributed environments. ↓

fix Refer to the Docket documentation for the specific backend chosen. Implement proper connection pooling, error handling, and retry mechanisms for backend connections. Misconfigurations can lead to lost tasks or inconsistent state.

breaking The `docket` package could not be found or installed from the available package index (e.g., PyPI). This typically indicates that the package is not published, the package name is misspelled, or the Python environment lacks access to the package index. ↓

fix Verify the correct package name (`docket`) and ensure it is published to PyPI or your configured package repository. Check network connectivity and `pip` configuration if using private repositories or proxies. If `docket` is not yet released, consider installing directly from source if available.

gotcha The `docket` library might not have pre-built wheels or be available for installation on all Python versions or architectures, particularly for newer Python releases (e.g., Python 3.13) or less common operating systems/architectures (e.g., Alpine Linux). This can lead to installation failures. ↓

fix Before attempting installation, verify Docket's PyPI page or documentation for supported Python versions and available distributions for your target environment. Consider using an officially supported Python version (e.g., 3.8-3.12) if encountering issues with newer releases or specific environments like Alpine Linux.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) build_error - - - -

3.10 alpine (musl) - - - -

3.10 slim (glibc) build_error - 1.5s - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) build_error - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) build_error - 1.4s - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) build_error - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) build_error - 1.3s - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) build_error - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) build_error - 1.3s - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) build_error - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) build_error - 1.6s - -

3.9 slim (glibc) - - - -

Imports

Docket
```
from docket import Docket
```
task
```
from docket import task
```
Cron
```
from docket.dependencies import Cron
```
Used for defining tasks that run on a cron schedule.

Quickstart last tested: 2026-04-24

A minimal example demonstrating how to define an asynchronous task and run it using Docket. This example uses the default in-memory backend.

import asyncio
from docket import Docket, task

@task
async def greet_task(name: str):
    """An example asynchronous task."""
    print(f"Hello, {name}!")
    return f"Greeted {name}"

async def main():
    # Initialize Docket. In a real application, you might configure a backend like Redis.
    docket = Docket()

    # Add the task to be run. This queues it for execution.
    await docket.add(greet_task, name="World")
    print("Task added. Running Docket...")

    # Run Docket. In a long-running service, this would be awaited indefinitely.
    # For a quickstart, we'll run it briefly to allow the task to execute.
    # For simplicity, we'll assume the task completes quickly.
    try:
        await asyncio.wait_for(docket.run(), timeout=5) # Run for max 5 seconds
    except asyncio.TimeoutError:
        print("Docket run timed out after 5 seconds.")

if __name__ == "__main__":
    asyncio.run(main())