Registry / workflow / procrastinate

procrastinate

JSON →
library3.8.1pypypiunverified

Procrastinate is an open-source Python 3.10+ distributed task processing library that leverages PostgreSQL 13+ to store task definitions, manage locks, and dispatch tasks. It integrates with both synchronous and asynchronous code, offers Django integration, and is compatible with ASGI frameworks, supporting features like periodic tasks, retries, and arbitrary task locks.

pip install procrastinate psycopg[binary]
INSTALL
IMPORT
SIG · PROCRASTINATE
P
procrastinate
workflowpythonv3.8.1
Install
2.7s avg
Import
639ms
Disk
38MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.8.1 · 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
musl
py 3.103.940 runs
installs and imports cleanly · install 0.0s · import 0.668s · 39.9MB
glibc
py 3.103.940 runs
installs and imports cleanly · install 2.7s · import 0.609s · 43MB
38MB installed
● package 38MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

App
from procrastinate import App
The main entry point for defining and managing tasks.
PsycopgConnector
from procrastinate import PsycopgConnector
Used to configure the connection to a PostgreSQL database.

This quickstart demonstrates how to define a Procrastinate application, declare a task, and defer a job. It assumes a PostgreSQL database is running and accessible via `POSTGRES_DSN`. To run the worker that executes deferred tasks, a separate CLI command is provided.

import random import time import os from procrastinate import App, PsycopgConnector # Configure your PostgreSQL connection string # Example: 'postgresql://user:password@host:port/database' # Use os.environ.get for production readiness POSTGRES_DSN = os.environ.get('POSTGRES_DSN', 'postgresql://postgres:password@localhost:5432/postgres') app = App( connector=PsycopgConnector( dsn=POSTGRES_DSN ) ) @app.task(name="sum_task") def sum_task(a, b): time.sleep(random.random() * 0.5) # Simulate work result = a + b print(f"Task sum_task({a}, {b}) finished with result: {result}") return result async def main(): print("Applying schema...") await app.open_async() await app.get_connector().check() await app.get_connector().execute_query_one("SELECT 1 FROM procrastinate_jobs LIMIT 1") print("Schema applied and checked.") print("Deferring a job...") job = await sum_task.defer_async(a=3, b=5) print(f"Job deferred with ID: {job.id}") await app.close_async() if __name__ == "__main__": import asyncio asyncio.run(main()) # To run the worker, save the above as e.g., 'my_tasks.py' and execute in a separate terminal: # export POSTGRES_DSN='postgresql://postgres:password@localhost:5432/postgres' # (or your actual DSN) # procrastinate --app=my_tasks.app worker
procrastinate --version
Debug
Known issues
breakingThe database migration process has significantly changed in major versions (e.g., around v1.0). Migrations are now categorized as 'pre' and 'post', requiring specific application before and after deploying new Procrastinate code. Ensure you consult the migration documentation for your upgrade path.
fix
Review the official 'Migration documentation' for your specific version upgrade. Apply 'pre' migrations before deployment and 'post' migrations after.
affects: 1.0.0+
breakingPython 3.9 support has been dropped in recent versions (e.g., 3.7.0), while support for Python 3.14 has been added. Ensure your environment uses a supported Python version (3.10+).
fix
Upgrade your Python environment to version 3.10 or later. Check the official documentation for the latest supported Python versions.
affects: 3.7.0+
gotchaWorkers must be aware of all task definitions. If tasks are in modules not directly imported by your `App` object or not specified in `App(import_paths=...)`, the worker will fail with a `TaskNotFound` error when attempting to execute such tasks.
fix
Explicitly list all modules containing task definitions in the `import_paths` parameter when initializing your `App` instance, or ensure they are imported as a side effect when the `App` is instantiated.
affects: All
gotchaProcrastinate is asynchronous at its core. While it offers synchronous deferral methods, running workers or interacting with the CLI requires an asynchronous context. Synchronous task functions executed by an async worker run in a thread, impacting parallelism for CPU-bound tasks due to the GIL.
fix
Understand the implications of async/sync boundaries. For synchronous task functions, be aware they run in a thread pool. For I/O-bound tasks, this is often fine. For CPU-bound tasks, consider making them `async` if possible or using other multiprocessing approaches if true parallelism is needed.
affects: All
Upgrade
Version history
3.8.1latest on PyPI · released Apr 8, 2026
Audit
Dependencies
PostgreSQLrequiredRequired as the backend for job storage, locks, and task dispatch. Version 13+ is recommended.
psycopgoptionalPython adapter for PostgreSQL, typically used with PsycopgConnector. 'psycopg[binary]' is often used for easier installation.
aiopgoptionalAlternative asynchronous PostgreSQL adapter, can be used with AiopgConnector.
Agent activity
35 hits · last 30 days
node
32
OpenAI (training)
1
Resources
procrastinate — pip install procrastinate · libregistry