RQ (Redis Queue)

2.7.0 · active · verified Fri Mar 27

Simple Python job queue backed by Redis or Valkey. Current version is 2.7.0. Requires Python >=3.9, Redis >=5 or Valkey >=7.2. Much simpler than Celery — no broker config, just a Redis connection. Key API change: job.result property removed in 1.12, replaced by job.return_value(). job.get_status() now returns a JobStatus enum, not a string.

Warnings

breaking job.result property removed in rq 1.12.0. Accessing job.result raises AttributeError. All tutorials and LLM-generated code using job.result are broken.
Fix: Replace job.result with job.return_value(). Note it returns None until the job completes.
breaking job.get_status() returns a JobStatus enum (e.g. JobStatus.FINISHED) not a string ('finished'). Comparing with strings like if job.get_status() == 'finished' always evaluates to False.
Fix: from rq.job import JobStatus; if job.get_status() == JobStatus.FINISHED: ... Or use job.is_finished, job.is_failed, job.is_started properties.
breaking Python 3.8 support dropped. Minimum is Python 3.9.
Fix: Pin rq<2.0 for Python 3.8 environments.
breaking redis-py 6.0.0 is explicitly blocked — rq will refuse to install with redis==6.0.0 due to critical incompatibilities. Use redis>=4.0.0,!=6.0.0.
Fix: Pin redis!=6.0.0 in requirements. Use redis>=4.0.0,!=6.0.0 or upgrade to a later redis-py patch once fixed.
gotcha Enqueued functions must be importable by the worker process. Functions defined in __main__ or interactively (notebooks, scripts run directly) cannot be pickled and will raise PicklingError.
Fix: Define task functions in separate module files (e.g. tasks.py). The worker imports them by module path.
gotcha Workers must be started in a separate process. Running rq worker in the same process as enqueuers causes deadlocks. Workers run: rq worker [queue_name]
Fix: Start worker in a separate terminal: rq worker. Or use WorkerPool for multiple workers: from rq import WorkerPool; WorkerPool(queues=[q], connection=redis_conn).start()
gotcha On Windows and macOS, the default Worker uses fork() which is not available. Use SpawnWorker instead, which uses multiprocessing.spawn.
Fix: from rq import SpawnWorker; SpawnWorker(queues=[q], connection=redis_conn).work(). Or use SimpleWorker for testing (no fork/spawn, runs in-process).

Install

pip install rq Standard

Imports

Queue

from redis import Redis
from rq import Queue

# Connection required at Queue creation time
redis_conn = Redis(host='localhost', port=6379, db=0)
q = Queue(connection=redis_conn)

# Functions must be importable — define in a module, not __main__
from myapp.tasks import process_data
job = q.enqueue(process_data, arg1, arg2)

# Get result (rq >= 1.12)
result = job.return_value()  # None until job completes

# Check status — returns JobStatus enum, not string
from rq.job import JobStatus
status = job.get_status()
if status == JobStatus.FINISHED:
    print(job.return_value())

job.result property was removed in rq 1.12.0 — use job.return_value() instead. job.get_status() returns a JobStatus enum since rq 1.x — compare with JobStatus.FINISHED not the string 'finished'.

Quickstart

Start Redis first, then run worker: rq worker. Functions must be in importable modules.

# tasks.py — functions must be in an importable module
def add(x, y):
    return x + y

def send_email(to, subject, body):
    # ... email logic
    return True


# enqueue.py — enqueue jobs
from redis import Redis
from rq import Queue
from tasks import add

redis_conn = Redis()
q = Queue(connection=redis_conn)

# Enqueue
job = q.enqueue(add, 4, 6)
print('Job ID:', job.id)

# Enqueue with options
job2 = q.enqueue(
    add, 10, 20,
    job_timeout=300,    # seconds before job is killed
    result_ttl=500,     # seconds to keep result in Redis
    retry=3             # retry on failure
)

# Check result (after worker runs)
import time
time.sleep(1)
print(job.return_value())  # 10
print(job.get_status())    # JobStatus.FINISHED

# --- Start worker in separate terminal ---
# rq worker

view raw JSON →