pytest-celery

library1.3.0pypypi✓ verified 25d ago

pytest-celery is a pytest plugin that provides fixtures and utilities for testing Celery applications. It streamlines setting up and tearing down Celery workers and brokers (like Redis, RabbitMQ, SQS) within your pytest test suite. Currently at version 1.3.0, it maintains an active development pace with frequent updates to support new Python and Celery versions, and address compatibility issues.

testing workflow

pip install "pytest-celery[all]"

github ↗package ↗

INSTALL

IMPORT

SIG · PYTEST-CELERY

pytest-celery

testingpythonv1.3.0

Install

7.8s avg

Import

—

Disk

77MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.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

musl

glibc

py 3.10

1/2 runs

✓ 8.2s

py 3.11

1/2 runs

✓ 7.7s

py 3.12

1/2 runs

✓ 7.2s

py 3.13

1/2 runs

✓ 6.95s

py 3.9

1/2 runs

✓ 9.1s

77MB installed

● package 77MB

Code

Verified usage

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

pytest_celery fixtures

✓ import pytest; # Fixtures like celery_app, celery_worker are auto-discovered

pytest-celery primarily provides fixtures (e.g., `celery_app`, `celery_worker`, `celery_session_app`, `celery_session_worker`) that are automatically discovered and made available to your test functions. Direct imports from `pytest_celery` modules are less common for basic usage, but may be used for advanced customization like `CeleryTestCluster`.

This quickstart demonstrates a basic test for a Celery task using pytest-celery's fixtures. It configures Celery to use Redis, starts a worker, and executes a task. Ensure your test environment has a running Redis instance or adjust the `celery_config` fixture accordingly. Remember to replace `my_app.tasks` with the actual path to your Celery tasks.

import pytest from celery import Celery @pytest.fixture(scope="session") def celery_config(): return { "broker_url": "redis://localhost:6379/0", "result_backend": "redis://localhost:6379/0", "task_always_eager": False, "task_eager_propagates": False } @pytest.fixture(scope="session") def celery_enable_logging(): return True @pytest.fixture(scope="session") def celery_worker_parameters(): return { 'queue': ['celery'], 'pool': 'solo' } # Assuming you have a tasks.py module with a simple task # e.g., tasks.py: # from celery import shared_task # @shared_task # def add(x, y): # return x + y def test_add_task(celery_app: Celery, celery_worker): # Ensure tasks.py is discoverable, e.g., by adding a custom Celery app fixture # or importing tasks directly if they are in the test file. from my_app.tasks import add # Replace with your actual task module result = add.delay(2, 3) assert result.get(timeout=10) == 5 assert result.successful()

Debug

Known issues

breakingPython 3.8 support was dropped in `pytest-celery` v1.3.0. Users on Python 3.8 must upgrade their Python environment or pin `pytest-celery` to a version prior to 1.3.0.

fix

Upgrade Python to 3.9 or higher, or pin `pytest-celery<1.3.0` in your project dependencies.

affects: >=1.3.0

gotchaThe `pycurl` dependency for SQS transport was removed in v1.2.0 (in favor of `urllib3`) and then re-added in v1.3.0 to match `celery`/`kombu` v5.6 SQS transport requirements. This flip-flop can cause unexpected dependency issues for users relying on SQS brokers, depending on their `pytest-celery` and `celery`/`kombu` versions.

fix

If experiencing SQS transport issues, check your installed `celery` and `kombu` versions against `pytest-celery`'s dependency requirements. You may need to manually install `pycurl` (e.g., `pip install 'pytest-celery[sqs]'`) or ensure `urllib3` is correctly used, depending on the `pytest-celery` version.

affects: 1.2.x, 1.3.x

gotchaBy default, `celery_app` and `celery_worker` fixtures have a `function` scope, meaning they are created and torn down for each test. For performance, especially with many tests, consider using the `session` scoped fixtures (`celery_session_app`, `celery_session_worker`) or customizing the scope of the default fixtures.

fix

Use `celery_session_app` and `celery_session_worker` fixtures for session-scoped Celery instances, or define your own fixtures with `scope='session'` or `scope='module'`.

affects: All versions

gotchaFrom v1.3.0, `setuptools` was removed from dependencies. While not directly breaking for users, projects with custom build systems or highly specific environments that previously relied on `pytest-celery` implicitly bringing `setuptools` might need adjustments.

fix

Ensure `setuptools` is explicitly listed as a dependency if your project's build process requires it, rather than relying on transitive installation.

affects: >=1.3.0

Errors

Common errors & fixes

fixture 'celery_worker' not found

The `pytest-celery` plugin is not installed, not active, or pytest cannot discover its provided fixtures.

fix

Ensure `pytest-celery` is correctly installed (`pip install pytest-celery`) and that your pytest environment can discover the plugin. If running in a virtual environment, confirm it is activated.

Unknown option: --celery-app

The `pytest-celery` plugin is either not installed, not enabled, or an outdated version is being used that does not recognize the `--celery-app` command-line option.

fix

Install or upgrade `pytest-celery` to the latest version (`pip install -U pytest-celery`) and ensure the command is run in an environment where the plugin is active.

Timeout waiting for celery worker to start

The Celery worker process managed by `pytest-celery` failed to start or connect to its broker within the default timeout period, often due to broker issues, misconfiguration, or slow startup.

fix

Increase the timeout using `--celery-worker-timeout=<seconds>` in your pytest command, verify your Celery app configuration, ensure the broker (e.g., Redis, RabbitMQ) is running and accessible, and check the worker's startup logs for specific errors.

ModuleNotFoundError: No module named 'your_project.celery_app'

The Python module path provided to the `--celery-app` command-line option cannot be found or imported by pytest-celery, indicating the module is not on the `PYTHONPATH` or the path is incorrect.

fix

Adjust your `PYTHONPATH` environment variable or ensure you are running `pytest` from a directory where `your_project.celery_app` is importable, for example, `pytest --celery-app=my_app.celery` when `my_app/celery.py` exists.

Upgrade

Version history

1.3.0latest on PyPI · released Mar 2, 2026

Audit

Dependencies

pytestrequiredCore testing framework.

celeryrequiredCore async task queue framework.

redisoptionalRequired for Redis broker/backend support (via 'redis' extra).

boto3optionalRequired for AWS SQS broker support (via 'sqs' extra).

pycurloptionalRe-added in v1.3.0 for SQS transport compatibility with specific Kombu versions. May be required for SQS broker support depending on Celery/Kombu version.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/celery/pytest-celery ↗

packagehttps://pypi.org/project/pytest-celery/ ↗