Registry / workflow / taskiq

taskiq

JSON →
library0.12.6pypypi✓ verified 22d ago

Taskiq is an asynchronous distributed task queue for Python, inspired by projects like Celery and Dramatiq. It supports both synchronous and asynchronous functions and integrates with popular async frameworks like FastAPI and AioHTTP. Taskiq is actively maintained with frequent releases, currently at version 0.12.1.

pip install taskiq
INSTALL
IMPORT
SIG · TASKIQ
T
taskiq
workflowpythonv0.12.6
Install
6.9s avg
Import
1064ms
Disk
46MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.12.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.915 runs
installs and imports cleanly · install 0.0s · import 1.135s · 45.4MB
glibc
py 3.103.915 runs
installs and imports cleanly · install 6.9s · import 0.992s · 47MB
46MB installed
● package 46MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

InMemoryBroker
from taskiq import InMemoryBroker
Used for quick local development without external services.
TaskiqScheduler
from taskiq import TaskiqScheduler
Used to schedule tasks.
TaskiqAdminMiddleware
from taskiq.middlewares.taskiq_admin_middleware import TaskiqAdminMiddleware
Middleware for integrating with the Taskiq Dashboard.
RedisStreamBroker
from taskiq_redis import RedisStreamBroker
Example for importing a specific broker (e.g., Redis).
RedisAsyncResultBackend
from taskiq_redis import RedisAsyncResultBackend
Example for importing a specific result backend (e.g., Redis).

This quickstart demonstrates how to define and execute an asynchronous task using Taskiq's `InMemoryBroker`. It covers defining a broker, decorating a function as a task, sending the task using `.kiq()`, and retrieving its result with `.wait_result()`. For distributed usage, an external worker process would be started to consume tasks from a real broker (like Redis or RabbitMQ).

import asyncio from taskiq import InMemoryBroker # 1. Create a broker instance. # InMemoryBroker is for local development only. For production, use taskiq-redis, taskiq-aio-pika, etc. broker = InMemoryBroker() # 2. Define a task using the broker's decorator. @broker.task async def add_numbers(a: int, b: int) -> int: print(f"Executing add_numbers({a}, {b})") await asyncio.sleep(0.1) # Simulate some async work return a + b async def main(): # 3. Startup the broker. This is crucial for proper functioning. await broker.startup() # 4. Send the task to the broker. task = await add_numbers.kiq(1, 2) # 5. Wait for the result. result = await task.wait_result(timeout=5) if result.is_err: print(f"Task failed: {result.error}") else: print(f"Task result: {result.return_value}") # 6. Shutdown the broker. await broker.shutdown() if __name__ == "__main__": asyncio.run(main()) # To run with a worker (for distributed brokers, e.g., Redis): # 1. Save the above code as 'my_app.py'. # 2. Start an external broker (e.g., Redis). # 3. Run the worker from your terminal: # taskiq worker my_app:broker # 4. Run the Python script (my_app.py) to send tasks.
taskiq --version
Debug
Known issues
breakingSupport for Python 3.9 was dropped in Taskiq version 0.12.0. Users on Python 3.9 must either upgrade their Python version or stay on an older Taskiq release.
fix
Upgrade Python to 3.10 or higher. If unable to upgrade, pin Taskiq to `<0.12.0` in your `requirements.txt`.
affects: >=0.12.0
gotchaThe `InMemoryBroker` is designed for local development and testing only. It does not send messages over a network and cannot be used for distributed task execution in production environments.
fix
For production, use a dedicated broker like `taskiq-redis`, `taskiq-aio-pika`, or `taskiq-nats`, which require separate installation and an external message queue service.
affects: All
gotchaCalling `broker.startup()` and `broker.shutdown()` is essential for all brokers. Failing to call `startup()` can lead to undefined behavior or tasks not being processed, while `shutdown()` ensures resources are properly released.
fix
Always include `await broker.startup()` at the beginning and `await broker.shutdown()` at the end of your client-side application's lifecycle, typically within `asyncio.run()` or your main application entry point.
affects: All
gotchaIn Taskiq `0.12.0`, `TaskiqAdminMiddleware` did not correctly handle tasks with `dataclasses` in their arguments or return values, leading to serialization issues.
fix
Upgrade to Taskiq `0.12.1` or newer, where this issue has been resolved. If upgrading is not immediately possible, avoid using `dataclasses` with tasks monitored by `TaskiqAdminMiddleware` on `0.12.0`.
affects: 0.12.0
gotchaWhen using `taskiq worker --fs-discover` (file system discover) with the default `--tasks-pattern 'task.py'`, Taskiq may attempt to import `task.py` files from third-party libraries installed in your virtual environment, leading to `ImportError` or unexpected behavior.
fix
Specify a more unique `--tasks-pattern` (e.g., `my_tasks.py`) or explicitly list task modules: `taskiq worker your_app.broker:broker your_app.tasks.module_a your_app.tasks.module_b`.
affects: All
gotchaThe `ZeroMQBroker` is explicitly stated to be suitable for projects with only ONE worker process. If multiple workers are connected to a `ZeroMQBroker`, tasks will be executed N times (where N is the number of workers) due to ZMQ's publish-subscribe architecture.
fix
If using `ZeroMQBroker`, ensure you run only a single worker instance (e.g., `taskiq worker your_app:broker -w 1`). For multi-worker setups, choose a different broker like Redis or RabbitMQ.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'taskiq_redis'
The taskiq_redis package, which provides the Redis broker implementation for Taskiq, was not installed.
fix
pip install "taskiq[redis]"
AttributeError: module 'your_worker_file' has no attribute 'app'
The Taskiq worker command-line interface could not find the TaskiqApp instance named 'app' in the specified module, or the module path was incorrect.
fix
Ensure your worker file (e.g., your_worker_file.py) contains a TaskiqApp instance named 'app', or specify the correct name and module path when running the worker: `taskiq worker your_worker_file:my_app_instance`
TypeError: Cannot serialize object of type datetime.datetime
The default MsgpackSerializer (or another chosen serializer) cannot directly serialize complex Python objects like datetime.datetime instances without custom handling.
fix
Convert the object to a serializable format (e.g., `datetime_obj.isoformat()`) before passing it to the task, or configure a custom serializer with appropriate encoders/decoders for these types.
TypeError: __init__ missing 1 required positional argument: 'broker'
The TaskiqApp instance was initialized without providing a broker instance, which is a mandatory argument for the application to function.
fix
Instantiate a broker (e.g., `InMemoryBroker`, `RedisBroker`) and pass it to the TaskiqApp constructor: `from taskiq import TaskiqApp, InMemoryBroker
app = TaskiqApp(broker=InMemoryBroker())`
AttributeError: 'TaskiqApp' object has no attribute 'add_task'
The `add_task` method on `TaskiqApp` was removed in Taskiq v0.10.0 and newer versions. Tasks should now be registered using the `@app.task` decorator.
fix
Replace calls like `app.add_task(my_func)` with decorating the function directly: `@app.task
def my_func():
    pass`
Upgrade
Version history
0.12.6latest on PyPI · released Aug 29, 2026
Audit
Dependencies
pythonrequiredTaskiq requires Python 3.10 or higher (up to Python 3.13) to run.
taskiq-redisoptionalProvides Redis broker and result backend, commonly used for distributed setups.
taskiq-aio-pikaoptionalProvides RabbitMQ broker, another popular choice for production deployments.
taskiq-natsoptionalProvides NATS broker, recommended for production use cases.
watchdogoptionalRequired for the `reload` extra, used for hot-reloading workers during development.
prometheus_clientoptionalRequired for the `metrics` extra, used to expose Prometheus metrics.
Agent activity
37 hits · last 30 days
node
32
OpenAI (training)
1
Resources
taskiq — pip install taskiq · libregistry