{"id":2808,"library":"timeout-decorator","title":"Timeout Decorator","description":"The `timeout-decorator` library provides a simple Python decorator to enforce execution time limits on functions. It primarily uses Unix signals for timeouts in the main thread but offers a multiprocessing strategy for use in other threads or on Windows. The library is currently at version 0.5.0, with its last release in 2020, but it remains a commonly used solution for function timeouts.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/pnpnpn/timeout-decorator","tags":["timeout","decorator","concurrency","signals","multiprocessing","utility"],"install":[{"cmd":"pip install timeout-decorator","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary decorator for applying timeouts.","symbol":"timeout","correct":"from timeout_decorator import timeout"}],"quickstart":{"code":"import time\nimport timeout_decorator\n\n@timeout_decorator.timeout(5)\ndef long_running_function():\n    print(\"Starting long_running_function...\")\n    for i in range(1, 10):\n        time.sleep(1)\n        print(f\"{i} seconds have passed inside function\")\n    print(\"long_running_function completed.\")\n\n@timeout_decorator.timeout(3, use_signals=False)\ndef another_long_running_function():\n    print(\"Starting another_long_running_function with multiprocessing strategy...\")\n    for i in range(1, 10):\n        time.sleep(1)\n        print(f\"{i} seconds have passed inside function\")\n    print(\"another_long_running_function completed.\")\n\nif __name__ == '__main__':\n    print(\"--- Testing signal-based timeout ---\")\n    try:\n        long_running_function()\n    except timeout_decorator.TimeoutError:\n        print(\"long_running_function timed out after 5 seconds.\")\n    print(\"\\n--- Testing multiprocessing-based timeout ---\")\n    try:\n        another_long_running_function()\n    except timeout_decorator.TimeoutError:\n        print(\"another_long_running_function timed out after 3 seconds.\")\n","lang":"python","description":"This example demonstrates basic usage with both the default signal-based timeout and the multiprocessing strategy. The `long_running_function` will time out after 5 seconds using signals, while `another_long_running_function` will time out after 3 seconds using the multiprocessing approach, useful for non-main threads or Windows."},"warnings":[{"fix":"Use `@timeout(seconds, use_signals=False)` when decorating functions in non-main threads or on Windows.","message":"The default signal-based timeout strategy (when `use_signals=True` or omitted) only works in the main thread on Unix-like operating systems. It is not compatible with Windows or functions running in non-main threads. For these cases, you must explicitly pass `use_signals=False` to switch to a multiprocessing-based strategy.","severity":"gotcha","affected_versions":"<=0.5.0"},{"fix":"Ensure all inputs and outputs of the timed-out function are compatible with Python's `pickle` module. Avoid complex objects or closures that cannot be serialized.","message":"When using the multiprocessing strategy (`use_signals=False`), all arguments passed to the decorated function and any values returned by it must be picklable. If they are not, the function call will fail with a `PicklingError`.","severity":"gotcha","affected_versions":"<=0.5.0"},{"fix":"For nested timeouts, set `use_signals=False` for all inner decorators. The outermost decorator can optionally use signals if it's in the main thread.","message":"Signal-based timeouts do not support nesting. If an outer function and an inner function are both decorated with `timeout` using signals, the inner timeout will cancel and override the outer one. Only one `SIGALRM` can be active per process.","severity":"gotcha","affected_versions":"<=0.5.0"},{"fix":"Refine exception handling within timed-out functions to catch specific exceptions rather than broad `Exception` clauses, or ensure `TimeoutError` is re-raised.","message":"Functions decorated with `@timeout` can inadvertently suppress `TimeoutError` if they broadly catch exceptions (e.g., `except Exception:`). This can prevent the timeout mechanism from effectively terminating the function or raising the expected error.","severity":"gotcha","affected_versions":"<=0.5.0"},{"fix":"While no official fix is provided within `timeout-decorator` v0.5.0, consider using alternative, more actively maintained timeout libraries (e.g., `wrapt-timeout-decorator`) for newer Python versions if issues arise.","message":"Some users have reported compatibility issues with `timeout-decorator` on Python 3.8 and newer versions, specifically related to changes in internal function naming, which could lead to `AttributeError` or unexpected behavior.","severity":"gotcha","affected_versions":">=3.8"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}