---
id: pytest-celery
version: "1.3.0"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# pytest-celery — Pytest plugin for Celery

License: permissive · Maintenance: active · Downloads: 1.9M/mo

## What it is and what it does

pytest-celery is the official testing plugin for Celery, the distributed task queue framework. It provides pytest fixtures and utilities to test Celery applications in two modes: traditional unit and integration testing via the celery.contrib.pytest API, and a newer Docker-based approach (introduced in version 1.0.0+) for smoke and production-like testing. The Docker-based methodology lets you spin up isolated Celery workers and brokers in containers, making it possible to test your tasks and application logic in environments that closely mirror production without affecting existing tests.

The plugin depends on celery, docker, kombu, debugpy, psutil, tenacity, and pytest-docker-tools. It supports Python 3.9 through 3.14 and is actively maintained. The low-friction install and production-stable status make it a straightforward addition to Celery-based projects that need comprehensive test coverage.

Use it for:

- Test Celery tasks in isolated Docker containers to verify behavior in production-like conditions before deployment.
- Write integration tests that spin up temporary Celery workers and brokers to validate task execution and message flow.
- Debug Celery application issues by running tests with debugpy attached to worker processes inside containers.
- Validate task retries, error handling, and signal handlers in a controlled Docker environment.
- Test multiple Celery workers and broker configurations without manual setup or teardown.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

pytest-celery is the official pytest plugin for Celery that enables testing of Celery applications using Docker-based environments to simulate production-like conditions, alongside traditional unit and integration testing APIs.

Yes, if you are testing a Celery application. pytest-celery is the official plugin, actively maintained, production-stable, and has no known vulnerabilities. The Docker-based testing approach (1.0.0+) is a significant enhancement for production-like validation. Low install friction and permissive licensing make it a straightforward choice for any Celery project.

## Install

pip install pytest-celery
uv add pytest-celery
poetry add pytest-celery

## Installing pytest-celery

Before you install: Low friction install with a pure-Python wheel. Actively maintained with recent commits and production-stable status. Depends on celery, docker, and pytest-docker-tools, which are standard testing dependencies.

License in practice: BSD-3-Clause is permissive and imposes no restrictions on use or redistribution; safe for commercial and open-source projects alike.

Quickstart:

pip install pytest-celery

import pytest
from pytest_celery import celery_app, celery_worker

def test_celery_task(celery_app, celery_worker):
    # Use fixtures to test Celery tasks
    pass

Docker must be installed and running; requires Python 3.9 or later.

Verify before relying:

- Whether the Docker-based approach requires specific Docker daemon configuration or network setup beyond standard Docker installation.
- Performance characteristics and overhead of Docker-based testing compared to traditional unit tests.

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest plugin for celery, celery testing with docker, celery task testing, distributed task queue testing, celery integration tests, production-like celery tests, celery worker testing, celery, distributed-testing, docker-based

[View on SkillFed](https://skillfed.io/packages/pytest-celery) · [View on PyPI](https://pypi.org/project/pytest-celery/)