Install & Compatibility
Where this runs
tested against v3.3.4 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.338s · 24.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.299s · 25MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Huey
✓ from huey import Huey
RedisHuey
✓ from huey import RedisHuey
✗ from huey.contrib.redis import RedisHuey
RedisHuey is now a top-level import as of Huey 2.x, simplifying common usage.
crontab
✓ from huey import crontab
This quickstart demonstrates how to set up Huey with a Redis backend, define a basic task, and a periodic task. It also shows how to enqueue tasks and retrieve their results. Remember to run a consumer process separately using `huey_consumer.py` to process tasks.
import os
from huey import RedisHuey, crontab
# Configure Huey with Redis, using an environment variable for host
REDIS_HOST = os.environ.get('REDIS_HOST', 'localhost')
huey = RedisHuey(host=REDIS_HOST)
# Define a simple task
@huey.task()
def add_numbers(a, b):
print(f"Adding {a} and {b}...")
return a + b
# Define a periodic task (runs every minute)
@huey.periodic_task(crontab(minute='*/1'))
def say_hello_every_minute():
print("Hello from a periodic task!")
if __name__ == '__main__':
# Enqueue tasks
print("Enqueuing tasks...")
result1 = add_numbers(10, 20)
result2 = add_numbers.schedule(args=(5, 5), delay=10)
print(f"Task 1 enqueued. Result ID: {result1.id}")
print(f"Task 2 scheduled. Result ID: {result2.id}")
# To run the consumer in a separate terminal:
# huey_consumer.py my_app.huey
# (assuming this code is in a file named my_app.py)
# To get a result (blocking):
# print(f"Result of task 1: {result1.get(blocking=True, timeout=5)}")
huey_consumer --version
Debug
Known issues
gotchaThe `SIGNAL_ENQUEUED` signal, introduced in 2.5.3, runs in the *calling process* (i.e., your main application), not the separate consumer process. Operations within this signal handler directly impact your application's request/response cycle.fixBe mindful of the operations performed within `SIGNAL_ENQUEUED` handlers. Avoid long-running, blocking, or resource-intensive tasks, as they will degrade the performance of your main application.
affects: 2.5.3+
gotchaWhen using `greenlet` workers, `huey` expects `gevent.monkey.patch_all()` to have been called *before* the `Huey` instance is created. Failure to do so (or a missing `gevent` dependency) will result in a warning and potential concurrency issues or unexpected behavior.fixEnsure `gevent.monkey.patch_all()` is executed at the very beginning of your application's entry point if you intend to use `greenlet` workers. Also, ensure `gevent` is installed (`pip install huey[gevent]`).
affects: 2.5.0+ (when warning was explicitly added)
gotchaOlder Huey versions may have compatibility issues with newer Python releases. Specifically, versions `<2.5.1` may fail on Python 3.12+ due to `datetime.utcnow()` deprecation, and versions `<2.5.4` may have issues with multiprocessing start methods on Python 3.14+.fixTo ensure full compatibility with Python 3.12+ and 3.14+, upgrade Huey to at least version 2.5.4.
affects: <2.5.4
breakingHuey versions older than 2.4.3 are not compatible with `redis-py` 4.0.0+ due to significant API changes in `redis-py`. Attempting to use older Huey versions with `redis-py>=4.0.0` will result in runtime errors.fixIf using `redis-py` 4.0.0 or newer, upgrade Huey to at least 2.4.3. Alternatively, for older Huey versions, pin your `redis-py` dependency to `<4.0.0` (e.g., `redis-py<4.0.0`).
affects: <2.4.3
breakingThe `redis` client library must be installed when using `RedisHuey` (or any other Redis-backed Huey storage). Failure to install the `redis` client will result in a `huey.exceptions.ConfigurationError`.fixEnsure the `redis` client library is installed. This can be done by running `pip install huey[redis]` (recommended) or `pip install redis`.
affects: All versions when using Redis storage
breakingWhen initializing `RedisHuey`, the `redis-py` library must be installed. Failure to install `redis-py` will result in a `ConfigurationError` indicating the 'redis' module is not found.fixEnsure `redis-py` is installed by running `pip install redis`.
affects: 1.0.0+
Errors
Common errors & fixes
HueyException: <task_name> not found in TaskRegistry
The Huey consumer process started without correctly importing the module(s) where the task functions are defined, so they are not registered with the consumer.
fixEnsure that the module containing your Huey tasks is imported when the Huey object itself is imported by the consumer. For Django, ensure tasks are in a `tasks.py` file within an app, or explicitly import them. For non-Django, ensure your consumer points to a main module that imports both your `Huey` instance and all modules containing decorated tasks.
TypeError: can't pickle <object>` or `PicklingError`
Task arguments or return values must be serializable by `pickle` for Huey to store them in the queue and result store. Common unpicklable objects include database connections, open file handles, lambda functions, and complex class instances.
fixPass IDs, keys, or file paths as task arguments instead of direct objects. For instance, pass a user ID instead of a `User` model instance, and then fetch the object within the task. Ensure return values are also picklable types.
redis.exceptions.ConnectionError: Error <errno> connecting to <host>:<port>. Connection refused
The Huey consumer (or producer) cannot establish a connection to the Redis server, often due to the Redis server not running, incorrect host/port configuration, or firewall issues.
fixVerify that the Redis server is running and accessible from where Huey is being run. Check the `host`, `port`, and `password` parameters in your `RedisHuey` configuration, and ensure no firewalls are blocking the connection.
Error importing <module_path>
The `huey_consumer.py` command cannot find or import the specified module containing the `Huey` instance, usually due to an incorrect import path or the module not being on Python's `sys.path`.
fixEnsure the specified module path (e.g., `myapp.huey`) is correct and that the directory containing `myapp` is on your `PYTHONPATH` or you are running `huey_consumer.py` from the project's root directory. For Django, use `python manage.py run_huey`.
AttributeError: 'TaskWrapper' object has no attribute '<attribute>'
This error typically occurs when trying to access attributes directly on the `Result` object returned by a task invocation instead of calling `.get()` to retrieve the actual return value, or when misusing task pipelines.
fixAlways call `.get()` on the `Result` object to retrieve the task's return value. For pipelines, use `.s()` to chain tasks, not direct function calls or other attributes like `.a()`.
Upgrade
Version history
3.3.4latest on PyPI · released Aug 5, 2026
Audit
Dependencies
redisoptionalRequired for the RedisHuey backend, which is the most common and recommended storage for production.
geventoptionalRequired if using 'greenlet' workers for concurrent task execution.