{"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":"python","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,"search_vec":"'0.5.0':50 '2020':56 'common':61 'concurr':69 'current':47 'decor':2,6,12,68 'enforc':14 'execut':15 'function':19,65 'last':53 'librari':7,45 'limit':17 'main':29 'multiprocess':34,71 'offer':32 'primarili':21 'provid':8 'python':11 'releas':54 'remain':59 'signal':24,70 'simpl':10 'solut':63 'strategi':35 'thread':30,40 'time':16 'timeout':1,5,26,66,67 'timeout-decor':4 'unix':23 'use':22,37,62 'util':72 'version':49 'window':43","created_at":"2026-04-11T01:43:39.733111+00:00","updated_at":"2026-04-16T22:57:36.924629+00:00","problems":[{"fix":"pip install timeout-decorator","cause":"The `timeout-decorator` library has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'timeout_decorator'"},{"fix":"Apply the decorator with `use_signals=False` and `use_multiprocessing=True` (or `use_thread=True` for simpler thread-based scenarios without multiprocessing overhead).\n```python\nimport timeout_decorator\nimport time\n\n@timeout_decorator.timeout(5, use_signals=False, use_multiprocessing=True)\ndef my_function():\n    time.sleep(10)\n    return \"Done\"\n\ntry:\n    my_function()\nexcept timeout_decorator.TimeoutError:\n    print(\"Function timed out!\")\n```","cause":"The default signal-based timeout mechanism (`signal.SIGALRM`) is not supported on the current operating system (e.g., Windows) or when the decorated function is executed in a non-main thread.","error":"UserWarning: Cannot use SIGALRM signal, use multiprocessing timeout strategy"},{"fix":"Add parentheses to the decorator call, passing the timeout duration as the first argument.\n```python\nimport timeout_decorator\nimport time\n\n@timeout_decorator.timeout(1)\ndef my_function():\n    time.sleep(2)\n    return \"Done\"\n\ntry:\n    my_function()\nexcept timeout_decorator.TimeoutError:\n    print(\"Function timed out!\")\n```","cause":"The `@timeout_decorator.timeout` decorator was applied without parentheses, meaning it was treated as a function object rather than being called with the required timeout duration argument.","error":"TypeError: timeout() missing 1 required positional argument: 'timeout_duration'"},{"fix":"Explicitly import and catch `timeout_decorator.TimeoutError`.\n```python\nimport timeout_decorator\nimport time\n\n@timeout_decorator.timeout(1)\ndef long_running_function():\n    time.sleep(2)\n    return \"Completed\"\n\ntry:\n    long_running_function()\nexcept timeout_decorator.TimeoutError: # Correctly catches the library's specific exception\n    print(\"Function timed out as expected!\")\n```","cause":"The code attempts to catch Python's built-in `TimeoutError` (or one from another library like `concurrent.futures`) instead of the specific `timeout_decorator.TimeoutError` exception raised by this library.","error":"timeout_decorator.TimeoutError: Function timed out after X seconds (traceback when `except TimeoutError` is used)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/pnpnpn/timeout-decorator","docs":null,"changelog":null,"pypi":"https://pypi.org/project/timeout-decorator/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}