---
id: timeout-decorator
version: "0.5.0"
license: unclear
license_treatment: permissive
maintenance: dormant
---

# timeout-decorator — Timeout decorator

License: permissive · Maintenance: dormant · Downloads: 4.4M/mo

## What it is and what it does

timeout-decorator is a Python decorator that enforces execution time limits on functions by raising an exception when a function runs longer than a specified duration. It offers two strategies: signal-based timeouts (the default, which works only in the main thread) and multiprocessing-based timeouts (for worker threads and background tasks). The decorator is straightforward to use—you simply annotate a function with @timeout_decorator.timeout(seconds)—and you can customize the exception raised on timeout or switch timeout strategies with a parameter.

The package has been dormant since late 2020, with no active maintenance. It carries no known vulnerabilities and uses a permissive MIT license. The main trade-off is that signal-based timeouts are Unix-specific and thread-constrained, while multiprocessing timeouts require all return values to be picklable, which can be a significant limitation in some applications.

Use it for:

- Wrap long-running API calls or database queries to prevent indefinite hangs in web applications.
- Enforce time limits on worker thread tasks in background job systems or thread pools.
- Prevent runaway computations or infinite loops in untrusted or user-provided code.
- Add timeout protection to legacy functions without refactoring their internals.
- Limit execution time in test suites to catch performance regressions or deadlocks.

## Worth the install?

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

A decorator that enforces time limits on function execution, raising an exception if the function runs longer than a specified number of seconds.

Yes, with conditions. The package is simple, permissive, and solves a real problem with minimal overhead. However, it is dormant (last release 2020-11-15) and carries platform and threading constraints: signal-based timeouts are Unix-only and main-thread-only, and multiprocessing timeouts require picklable return values. Install it if you need a lightweight timeout decorator for main-thread code or if you are willing to work around the multiprocessing limitations; avoid it if you need active maintenance or cross-platform signal handling.

## Install

pip install timeout-decorator
uv add timeout-decorator
poetry add timeout-decorator

## Installing timeout-decorator

Before you install: High install friction: the package is dormant (last release 2020-11-15, no commits since 2024-01-12) and depends on platform-specific signal handling or multiprocessing, which may require system-level setup or compatibility considerations.

License in practice: MIT license (permissive) means you can use, modify, and distribute this package freely with minimal restrictions, though you must include the license notice.

Quickstart:

pip install timeout-decorator

import time
import timeout_decorator

@timeout_decorator.timeout(5)
def mytest():
    print("Start")
    for i in range(1, 10):
        time.sleep(1)
        print("{} seconds have passed".format(i))

mytest()

Signal-based timeouts (default) only work in the main thread; use use_signals=False for worker threads, but then your function must return picklable objects.

Verify before relying:

- Whether the package works reliably with modern Python versions (python_support is unspecified in metadata)
- Current state of known issues or edge cases beyond the PicklingError fix in 0.3.1
- Whether signal-based timeouts are reliable across different operating systems

## Package facts

- License: not declared (permissive)
- Python support: unspecified
- Install friction: high
- Maintenance: dormant
- Downloads: 4.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

function timeout decorator, limit execution time, timeout exception handler, function execution time limit, prevent long-running functions, timeout signal handler, multiprocessing timeout, execution-control, threading

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