Install & Compatibility
Where this runs
tested against v0.14.0 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.548s · 26.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.0s · import 0.515s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Scheduler
✓ from rq_scheduler import Scheduler
This quickstart demonstrates how to instantiate `rq_scheduler.Scheduler` and schedule a job to run at a specific future time using `enqueue_at` and a recurring job using `cron`. Ensure your Redis server is running and that both `rq-scheduler` and `rq worker` processes are started separately for the scheduled jobs to be processed.
import os
from redis import Redis
from rq_scheduler import Scheduler
from datetime import datetime, timedelta
def my_job(arg1, arg2):
print(f'Running job with args: {arg1}, {arg2}')
return arg1 + arg2
# Ensure a Redis connection is available. Use a default if REDIS_URL not set.
redis_url = os.environ.get('REDIS_URL', 'redis://localhost:6379')
redis_conn = Redis.from_url(redis_url)
# Instantiate the scheduler with the Redis connection
scheduler = Scheduler(connection=redis_conn)
# Example 1: Schedule a job to run once at a specific time
job_at_time = datetime.utcnow() + timedelta(seconds=10)
scheduler.enqueue_at(
job_at_time, # Time to run the job
my_job, # Function to be called
'hello', 'world' # Arguments for the function
)
print(f"Scheduled 'my_job' to run at {job_at_time} UTC")
# Example 2: Schedule a recurring job using cron syntax (every minute)
# Note: This will repeatedly add the job to the queue based on the cron string.
# Ensure 'rq-scheduler' process is running for this to work.
scheduler.cron(
'*/1 * * * *', # Cron string (every minute)
func=my_job, # Function to be called
args=('cron_arg1', 'cron_arg2'), # Arguments for the function
repeat=None, # Run indefinitely
queue_name='default' # Queue to add the job to
)
print("Scheduled 'my_job' to run every minute via cron")
# To run the scheduler, you would execute `rq-scheduler` in your terminal.
# To process jobs, you would execute `rq worker` in your terminal.
rqscheduler --version
Debug
Known issues
breakingRQ Scheduler v0.14.0 and later support RQ 2.0+. Using older versions of `rq-scheduler` with RQ 2.0+ or newer `rq-scheduler` with older RQ versions can lead to compatibility issues or errors.fixEnsure your `rq-scheduler` and `rq` package versions are compatible. For `rq-scheduler==0.14.0`, use `rq>=2.0.0`. Check `rq-scheduler` release notes for specific `rq` version requirements.
affects: <0.14.0 with RQ 2.0+, >=0.14.0 with RQ <2.0
breakingStarting with v0.13.0, `rq-scheduler` requires Python 3.6 or newer. Older Python versions are no longer supported.fixUpgrade your Python environment to 3.6 or newer. If you must use an older Python, stick to `rq-scheduler<0.13.0`.
affects: <0.13.0 (for Python 3.5 or earlier)
gotchaThe `rq-scheduler` process is separate from `rq` worker processes. You must run `rq-scheduler` via its command-line tool (`rq-scheduler`) and `rq` workers via `rq worker` for scheduled jobs to be added to the queue and then processed.fixStart both `rq-scheduler` and `rq worker` processes concurrently. E.g., in separate terminal tabs or managed by a process supervisor (like Supervisord or systemd).
affects: All
gotchaThe `rq-scheduler` instance must connect to the same Redis database as your `rq` workers and application. Using different Redis connections will result in jobs not being scheduled or processed correctly.fixPass the same `redis.Redis` connection object or connection parameters (e.g., `REDIS_URL`) to both your `Scheduler` instance and your `rq` workers.
affects: All
Errors
Common errors & fixes
rqscheduler: command not found
The `rq-scheduler` console script is not found in the system's PATH, typically because the package is not installed in the active Python environment.
fixEnsure `rq-scheduler` is installed in your current environment (`pip install rq-scheduler`) and that your virtual environment is activated if applicable.
ModuleNotFoundError: No module named 'rq_scheduler'
The `rq-scheduler` package has not been installed, or it's not installed in the Python environment currently in use.
fixInstall the `rq-scheduler` package using pip: `pip install rq-scheduler`.
redis.exceptions.ConnectionError: Error 111 connecting to 127.0.0.1:6379. Connection refused.
The Redis server, which `rq-scheduler` (and `rq`) requires for operation, is not running or is not accessible at the specified host and port.
fixStart your Redis server and ensure it's accessible from the machine where `rq-scheduler` is running. You might need to configure the Redis host and port if it's not running on localhost:6379.
TypeError: 'NoneType' object is not callable
This often occurs when trying to schedule a job by calling the function directly (e.g., `my_job()`) instead of passing the function reference and its arguments separately to `scheduler.enqueue_at` or `scheduler.enqueue_in`.
fixPass the job function itself as the second argument, followed by its arguments: `scheduler.enqueue_at(time, my_job, arg1, arg2)`.
Upgrade
Version history
0.14.0latest on PyPI · released Oct 29, 2024
Audit
Dependencies
rqrequiredCore dependency for task queuing; version compatibility is critical.
redisrequiredRequired for connecting to the Redis server where jobs and queue data are stored.
crontabrequiredUsed for parsing cron strings; replaced 'croniter' in v0.13.0.