Huey Task Queue

2.6.0 · active · verified Thu Apr 09

Huey is a lightweight, redis-backed task queue for Python applications. It supports thread, process, or greenlet workers, scheduling, retries, and result storage. The current version is 2.6.0, and it maintains an active release cadence with regular updates and compatibility fixes.

Warnings

gotcha The `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.
Fix: Be 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.
gotcha When 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.
Fix: Ensure `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]`).
gotcha Older 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+.
Fix: To ensure full compatibility with Python 3.12+ and 3.14+, upgrade Huey to at least version 2.5.4.
breaking Huey 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.
Fix: If 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`).

Install

pip install huey Install core Huey
pip install huey[redis] Install Huey with Redis backend

Imports

Huey
```
from huey import Huey
```
RedisHuey
```
from huey import RedisHuey
```
RedisHuey is now a top-level import as of Huey 2.x, simplifying common usage.
crontab
```
from huey import crontab
```

Quickstart

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)}")

view raw JSON →