timeout-decorator

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 on this page — 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

timeout-decorator on PyPI

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

Evidence: timeout-decorator-0.5.0.tar.gz

Tags

More Python Modules packages