🕐 handcron 💁

Python task queue with manual ticks

Unlike a traditional task queue, handcron is designed to process due tasks and then stop - by default, there is no long-running process in the background. Instead, you periodically run handcron tick yourself (from a cron, etc.).

It is similar to django-cron and anacron(8), but comes as a simple Python library with Huey-inspired API.

Installation

Simply uv add handcron or pip install handcron.

If you'd like to use PostgreSQL as your storage backend, install the postgres extra: uv add handcron[postgres] or pip install handcron[postgres].

Example

# my_tasks.py
from handcron import SqliteHandcron

cron = SqliteHandcron("handcron.sqlite")

@cron.periodic_task("@daily")
def my_task():
    print("Hello from my task")

$ handcron tick my_tasks.cron             # drain the queue once and exit
$ handcron serve my_tasks.cron            # drain the queue periodically
$ handcron oneshot my_tasks.cron my_task  # run a task without scheduling
$ handcron describe my_tasks.cron         # print task schedule and last run status

INFO     handcron.cli: Summary of instance 'handcron':
┌──────────┬─────────┬──────────────────────────────┬──────────────┬────────────┐
│ task     │ cron    │ last run                     │ start_date   │ end_date   │
├──────────┼─────────┼──────────────────────────────┼──────────────┼────────────┤
│ my_task  │ @daily  │ SUCCESS  2026-09-25 18:55:21 │              │            │
└──────────┴─────────┴──────────────────────────────┴──────────────┴────────────┘

handcron vs. alternatives

Celery, Huey, Apache Airflow

• handcron is much less resource intensive, since it works more like a serverless function than a background service. It won't prevent your CPU from entering a low-power state; the machine could even be turned off most of the time.
• handcron has no heavy dependencies and is easily run natively on Windows or Linux. With uv, your scheduled command can be as simple as: uv run --with handcron handcron tick my_tasks.cron

Plain cron(8), Systemd timer + service

• handcron can catch up with missed task runs, unlike cron(8).
• handcron keeps a database of past runs and their status, it has better visibility than flat logs.
• handcron allows you to define tasks on different schedules in one place.

License

MIT – see LICENSE.txt.