---
id: pebble
version: "5.2.1"
license: LGPL
license_treatment: copyleft
maintenance: active
---

# Pebble — Threading and multiprocessing eye-candy.

License: copyleft · Maintenance: active · Downloads: 1.5M/mo

## What it is and what it does

Pebble is a decorator-based library that simplifies running functions concurrently in threads or separate processes. It wraps Python's threading and multiprocessing modules with a cleaner API, allowing you to mark functions with @concurrent.thread or @concurrent.process and get back futures that you can poll or await. The library handles timeouts, error propagation (including remote tracebacks from worker processes), and provides pool abstractions for managing multiple workers with configurable restart and task limits.

The package is useful when you need to offload blocking I/O or CPU-bound work without writing boilerplate around futures and exception handling. It supports both synchronous and asyncio-based code paths, so you can use the same decorated functions in traditional or async contexts. With no external dependencies and support for current Python versions, it's straightforward to add to existing projects.

Use it for:

- Offload blocking I/O operations (file reads, network calls) to threads while keeping the main thread responsive.
- Run CPU-bound computations in separate processes to avoid Python's GIL and parallelize work.
- Enforce time limits on long-running tasks and handle timeouts gracefully without killing the process.
- Build worker pools for batch processing with automatic task distribution and error collection.
- Integrate concurrent execution into asyncio applications using the @asynchronous decorators.

## Worth the install?

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

Pebble provides decorators and pool abstractions to run functions in separate threads or processes, with timeout and error handling support.

Yes. Pebble is actively maintained, has no external dependencies, carries a copyleft license suitable for open-source work, and provides genuine convenience for concurrent programming. Install it if you need decorator-based thread or process management with timeout support; skip it if you need only basic threading or if your project cannot accept LGPL licensing.

## Install

pip install pebble
uv add pebble
poetry add pebble

## Installing Pebble

Before you install: Low friction installation with no runtime dependencies. Actively maintained with recent releases and a stable codebase since 2013.

License in practice: Licensed under LGPL (copyleft), which requires derivative works to be distributed under compatible terms; suitable for open-source projects but review is needed before use in proprietary software.

Quickstart:

pip install Pebble

from pebble import concurrent
from concurrent.futures import TimeoutError

@concurrent.process(timeout=10)
def function(foo, bar=0):
    return foo + bar

future = function(1, bar=2)
try:
    result = future.result()
except TimeoutError:
    print("Timed out")

Requires Python 3.8 or later.

Verify before relying:

- Whether process-based execution works reliably on Windows (multiprocessing platform differences not detailed in fact sheet).
- Performance characteristics and overhead compared to direct threading/multiprocessing for specific workload types.

## Package facts

- License: LGPL (copyleft)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.5M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

thread pool decorator, process pool management, concurrent function execution, timeout handling threads, async task scheduling, worker pool abstraction, thread process decorator, concurrency, multiprocessing, decorator-based

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