Install & Compatibility
Where this runs
tested against v1.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.406s · 32.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.366s · 33MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pytest.mark.<timeout_type>
✓ import pytest
@pytest.mark.execution_timeout(1.5)
def test_something():
...
Configuration is primarily done via pytest markers, command-line options, or pytest.ini, rather than direct imports of `pytest-timeouts` classes or functions.
This example demonstrates how to apply timeouts to the setup, execution, and teardown phases of a test using markers. The `test_timeout_phases` function's execution phase is intentionally set to exceed its defined timeout, which should cause a failure. You can also configure timeouts globally via `pytest.ini` or command-line options like `--setup-timeout`.
import time
import pytest
# Configure global timeouts in pytest.ini (optional):
# [pytest]
# setup_timeout = 0.3
# execution_timeout = 0.5
# teardown_timeout = 0.4
@pytest.mark.setup_timeout(0.3)
@pytest.mark.execution_timeout(0.5)
@pytest.mark.teardown_timeout(0.4)
def test_timeout_phases():
print("\nStarting setup (simulated)")
time.sleep(0.1) # Simulate setup
print("Starting execution (simulated)")
time.sleep(0.6) # This will exceed execution_timeout(0.5)
print("Starting teardown (simulated)")
time.sleep(0.1) # Simulate teardown
def test_no_timeout():
print("\nRunning test without explicit timeouts")
time.sleep(0.1)
# To run this test, save as test_example.py and execute:
# pytest -v test_example.py
Debug
Known issues
breakingThis plugin is explicitly 'Linux-only'. It relies on the SIGALRM signal, which is not reliably available or behaves differently on other operating systems like macOS or Windows. It will not function as expected on non-Linux platforms.fixEnsure usage only on Linux environments or consider the more general `pytest-timeout` plugin if cross-platform compatibility is required.
affects: All versions
gotchaThe `pytest-timeouts` plugin has a fixed order of precedence for applying timeout settings: command-line options (`opts`) > markers (`markers`) > `pytest.ini` (`ini`). This order can be customized or disabled using the `--timeouts-order` command-line option, e.g., `--timeouts-order oi` to prioritize `opts` then `ini` and disable markers.fixBe explicit about your desired timeout order using `--timeouts-order` if multiple configuration sources are used. Understand that command-line options generally override markers, which override `pytest.ini`.
affects: All versions since 1.0.0
gotchaWhen a test is terminated due to a timeout, especially with hard termination methods (like `os._exit()` which is often used), it may result in an abrupt exit without proper fixture teardown, incomplete JUnit XML output, or other post-test processing. While debugging information is usually preserved, be aware of these side-effects.fixDesign tests to be robust against abrupt termination. If graceful teardown is critical, explore `pytest-forked` for process isolation or use the `thread` timeout method (if available and suitable for your tests, though `pytest-timeouts` primarily uses `SIGALRM`). Review the plugin's documentation on termination methods.
affects: All versions
deprecatedVersion 1.2.1 fixed a `PyTest get_marker warning` that specifically affected `pytest 3.10.X`. This indicates potential compatibility issues or warnings when using `pytest-timeouts` with specific `pytest` versions, particularly around how markers are accessed. Newer `pytest` versions generally prefer `request.node.get_closest_marker`.fixUpgrade to `pytest-timeouts` version 1.2.1 or newer to resolve `get_marker` warnings with `pytest 3.10.X`. Ensure your `pytest` version is compatible with the `pytest-timeouts` version you are using.
affects: <1.2.1 with pytest >=3.10.0
gotchaThis plugin (`pytest-timeouts`) is distinct from the more widely known `pytest-timeout` plugin. `pytest-timeouts` is specifically designed for Linux and focuses on granular phase timeouts (setup, execution, teardown) using `SIGALRM`, whereas `pytest-timeout` offers broader OS support and different timeout mechanisms.fixCarefully choose the correct plugin based on your operating system and specific timeout requirements. If you need phase-specific timeouts on Linux, `pytest-timeouts` is the one. For general timeouts across platforms, `pytest-timeout` might be more appropriate.
affects: All versions
Errors
Common errors & fixes
ERROR: unknown option: --timeout
Users often confuse `pytest-timeouts` with the similarly named `pytest-timeout` plugin, attempting to use options from the latter which are not recognized by `pytest-timeouts`.
fixUse the specific options provided by `pytest-timeouts` such as `--setup-timeout`, `--execution-timeout`, or `--teardown-timeout` instead of `--timeout`.
pytest-timeouts plugin is designed for Linux. It may not work as expected on non-Linux systems.
The `pytest-timeouts` plugin is explicitly designed for Linux and relies on `os.fork()` and `signal.SIGALRM`, so this warning appears when the plugin is run on non-Linux operating systems like macOS or Windows.
fixRun your pytest suite in a Linux environment where `pytest-timeouts` can function correctly, or use a different timeout plugin designed for your platform.
pytest: error: argument --setup-timeout: invalid float value: 'abc'
A non-numeric or malformed value was provided for a timeout option which expects a float (e.g., '1.5', '10').
fixEnsure that all timeout options (e.g., `--setup-timeout`, `--execution-timeout`, `--teardown-timeout`) are provided with valid numeric (float) values.
ERROR: unknown option: --set_up-timeout
A command-line option for `pytest-timeouts` was misspelled, leading `pytest` to report it as an unrecognized argument.
fixCorrect the spelling of the option; for example, change `--set_up-timeout` to `--setup-timeout`.
TimeoutExpired: Timeout occurred during setup phase.
A specific phase of your test (setup, execution, or teardown) exceeded the time limit configured by `pytest-timeouts` for that phase.
fixIncrease the timeout for the respective phase using options like `--setup-timeout=<seconds>`, `--execution-timeout=<seconds>`, or `--teardown-timeout=<seconds>`, or optimize the code in that phase to run within the allotted time.
Upgrade
Version history
1.2.1latest on PyPI · released Sep 21, 2019
Audit
Dependencies
pytestrequiredCore testing framework; this is a plugin for pytest.