circuitbreaker

What it is and what it does

CircuitBreaker is a Python decorator that implements the Circuit Breaker pattern to protect distributed systems from cascading failures. When you decorate a function with @circuit, the decorator monitors execution, counts failures, and stops calling the function after a configurable threshold (default: 5 failures) is reached. After a recovery timeout (default: 30 seconds), it enters a half-open state to test whether the integration point has recovered.

The decorator supports both synchronous and asynchronous functions, and you can customize which exceptions trigger the circuit to open, set different failure thresholds and recovery timeouts, and provide fallback functions to execute when the circuit is open. It also integrates with a CircuitBreakerMonitor to track the health and state of all active circuit breakers in your application.

Use it for:

• Protect HTTP clients from repeatedly calling unavailable external APIs by opening the circuit after connection failures.
• Prevent database connection pools from exhausting resources when a database is temporarily down.
• Implement graceful degradation in microservices by using fallback functions when downstream services are unavailable.
• Monitor the health of multiple integration points across your application via CircuitBreakerMonitor.
• Rate-limit or fail fast on specific HTTP errors (e.g., 429 Too Many Requests) using custom exception logic.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Python decorator that implements the Circuit Breaker pattern to prevent cascading failures in distributed systems by monitoring function calls, counting failures, and stopping execution after a threshold is reached.

Yes. CircuitBreaker is a straightforward, dependency-free implementation of a well-established resilience pattern. It works with both sync and async code, has no install friction, and carries a permissive license. The aging maintenance status (last release 501 days ago) is a minor concern for a stable, narrowly-scoped library, but verify that its feature set and behavior match your needs before adopting it in production.

Install

circuitbreaker on PyPI

pip install circuitbreaker

uv add circuitbreaker

poetry add circuitbreaker

Installing circuitbreaker

Before you install

Low install friction with no runtime dependencies. Maintenance is aging—last commit was 2025-03-31 and the project has not released since then, though the repository remains active and not archived.

License in practice

BSD-3-Clause is a permissive license, allowing broad use, modification, and distribution with minimal restrictions.

Quickstart

from circuitbreaker import circuit

@circuit
def external_call():
    pass

# Or with configuration:
@circuit(failure_threshold=10, expected_exception=ConnectionError)
def external_call():
    pass

Verify before relying

• Whether the aging maintenance status (501 days since last release) affects stability or security for production use.
• Performance characteristics under high-concurrency or high-failure-rate scenarios.
• Compatibility with modern async frameworks beyond basic async/await support.

Package facts

Evidence: circuitbreaker-2.1.3-py3-none-any.whl

Tags

More Monitoring packages