Install & Compatibility
Where this runs
tested against v0.26.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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Celery
✓ from celery import Celery
✗ from celery-stubs import Celery
This quickstart demonstrates a basic Celery application with a type-hinted task. With `celery-types` installed, your type checker will validate the arguments and return types of Celery tasks and related objects like `AsyncResult`.
from celery import Celery, Task
from typing import Any, Dict
# Configure Celery app (replace with your broker/backend)
app = Celery(
'my_app',
broker=os.environ.get('CELERY_BROKER_URL', 'redis://localhost:6379/0'),
backend=os.environ.get('CELERY_RESULT_BACKEND', 'redis://localhost:6379/0')
)
# Define a type-hinted task
@app.task
def add(x: int, y: int) -> int:
return x + y
# Example of calling the task with type hints
if __name__ == '__main__':
# The type checker (e.g., MyPy) will use celery-types to validate arguments
result: AsyncResult[int] = add.delay(10, 20)
print(f"Task ID: {result.id}")
print(f"Result: {result.get()}")
# Incorrect usage (type checker would flag this if celery-types is installed)
# add.delay(10, "20") # Mypy would warn about this
Debug
Known issues
gotchaFor full generic type support in certain Celery classes (e.g., `Celery`, `Task`, `AsyncResult`), `celery-types` suggests a runtime monkey patch for `__class_getitem__`. Without this, generic type hints on these classes might not be fully recognized by type checkers.fixRefer to the `celery-types` GitHub README for the latest monkey-patching snippet to enable full generic support for relevant Celery classes in your application's entry point. This typically involves iterating over a list of Celery classes and setting their `__class_getitem__` attribute.
affects: All versions
gotchacelery-types provides *type stubs*, not runtime code. You should import Celery symbols from their original packages (e.g., `from celery import Celery`), and the installed `celery-types` package will automatically provide the type information to your type checker (e.g., MyPy). Attempting to import directly from `celery_types` will likely result in an `ImportError` or incorrect behavior.fixAlways import Celery classes and functions directly from the `celery` (or `kombu`, `django_celery_results`, etc.) packages. `celery-types` is a dependency for your type checker, not for runtime execution.
affects: All versions
breakingcelery-types is designed to provide type hints for specific versions of the underlying Celery library. Celery itself has undergone significant breaking changes, especially regarding Python version support (e.g., Celery 5.0 dropped Python 2.7, Celery 5.6.0 requires Python 3.9+). Using `celery-types` with an incompatible major version of `celery` can lead to incorrect or missing type information.fixAlways ensure your `celery-types` version is compatible with your installed `celery` version. Consult the `celery-types` release notes or `pyproject.toml` for supported `celery` ranges. Upgrade both `celery` and `celery-types` in tandem, following `celery`'s migration guides for runtime breaking changes.
affects: All versions, especially when upgrading Celery
gotchaWhile `celery-types` helps with type checking, it does not resolve runtime serialization issues in Celery. If you pass complex Python objects as task arguments, default JSON serialization might fail. Celery's default serializer changed from `pickle` to `json` in version 4.0. Using `pickle` is possible but less secure.fixFor complex objects, ensure they are JSON-serializable, or explicitly configure Celery to use a different serializer (e.g., `pickle` if security is less of a concern for internal communication), or pass only serializable data like IDs and retrieve complex objects within the task itself.
affects: Celery 4.0 and later (which celery-types supports)
Upgrade
Version history
0.26.0latest on PyPI · released Mar 12, 2026
Audit
Dependencies
typing-extensionsrequiredProvides backports of features from `typing` module for older Python versions, necessary for comprehensive type hinting.