Install & Compatibility
Where this runs
tested against v2.4.0 · 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.422s · 31.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.380s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pytest.mark.timeout
✓ import pytest
@pytest.mark.timeout(300)
def test_example():
pass
pytest-timeout is a plugin and typically configured via pytest.ini, command-line options, or test markers, rather than direct Python imports of its internal classes.
This quickstart demonstrates how to apply timeouts using `pytest-timeout`. It shows setting a global timeout via `pytest.ini` (or `PYTEST_TIMEOUT` environment variable), and overriding it for specific tests using the `@pytest.mark.timeout` decorator. The example includes tests that should pass and one designed to explicitly time out.
import pytest
import time
import os
# Example pytest.ini content (can be placed in a file named pytest.ini)
# [pytest]
# timeout = 5
# Or set via environment variable (e.g., in CI/CD)
# export PYTEST_TIMEOUT=10
# A test that should pass within the global timeout (if set to > 1)
def test_fast_operation():
time.sleep(1) # Simulates a quick operation
assert True
# A test with a specific timeout marker, overriding global settings
@pytest.mark.timeout(os.environ.get('PYTEST_LONG_TIMEOUT', 20))
def test_long_running_operation():
time.sleep(15) # Simulates a potentially long operation
assert True
# A test designed to time out if default or global timeout is low
@pytest.mark.timeout(2)
def test_should_timeout():
time.sleep(3) # This will exceed the 2-second mark
assert False, "Should not reach here if timeout works"
# To run these tests:
# 1. Save as a Python file (e.g., test_timeouts.py)
# 2. Run from your terminal: pytest test_timeouts.py
# (or pytest test_timeouts.py --timeout=5 to set a global CLI timeout)
pytest --version
Debug
Known issues
breakingMinimum `pytest` version has increased. For `pytest-timeout` versions 2.2.0 and later, `pytest>=7.0.0` is required. Ensure your `pytest` installation is up-to-date to avoid compatibility issues. Python 3.7+ is required for version 2.4.0.fixUpgrade pytest to `pytest>=7.0.0` using `pip install --upgrade pytest` and ensure Python is 3.7 or newer.
affects: 2.2.0+
gotchaThe plugin offers two timeout methods: 'signal' (default on supported systems) and 'thread'. The 'signal' method (using SIGALRM) is generally more efficient but can interfere with code under test that also uses SIGALRM. The 'thread' method is more portable and reliable but incurs more overhead and can prevent other `pytest` features (like JUnit XML or fixture teardown) from completing normally because it terminates the entire process.fixIf experiencing issues, explicitly set the method using `--timeout-method=thread` CLI option or `timeout_method = thread` in `pytest.ini`. Consider the implications of each method on your test suite's behavior.
affects: All
gotchaSession timeouts (`--session-timeout`) are 'cooperative'. They check the session time at the end of each test function and stop *further* tests from running if the timeout is exceeded. They will *not* interrupt a test currently in progress. To ensure a test-in-progress is interrupted, a per-function timeout must also be set.fixFor hard limits on individual test execution, always combine `--session-timeout` with global or per-test `timeout` settings. E.g., `pytest --session-timeout=3600 --timeout=300`.
affects: All
gotchaBy default, timeouts apply to the entire test lifecycle, including fixture setup and teardown. If your fixtures are long-running, they can cause tests to time out prematurely.fixIf you only want to time the test function body, set `timeout_func_only = True` in your `pytest.ini` file, or increase the timeout duration to account for fixture overhead.
affects: All
gotchaBy default, `pytest-timeout` attempts to detect when a debugger (like pdb or PyCharm's debugger) is active and disables timeouts to prevent interruption during debugging sessions. This behavior can be explicitly disabled.fixIf you need timeouts to function even when a debugger is attached (e.g., for automated debugging workflows), use the `--timeout-disable-debugger-detection` CLI option or `disable_debugger_detection = True` in `pytest.ini`.
affects: All
gotchaThe test execution environment generated warnings from `pip`. These typically include warnings about running `pip` as the 'root' user (which can cause permission issues) and notices about new `pip` versions being available. These are external to the tested library's functionality and do not indicate a failure of `pytest-timeout`.fixTo address the 'root' user warning, it is recommended to use a Python virtual environment (e.g., `python -m venv .venv` and `source .venv/bin/activate`). To update `pip`, run `pip install --upgrade pip`.
affects: pip: All versions when conditions (e.g., root user, outdated pip) are met.
Errors
Common errors & fixes
pytest: error: unrecognized arguments: --timeout=X
The `pytest-timeout` plugin is not installed or pytest cannot find it, so the `--timeout` command-line argument is not recognized.
fixInstall the plugin using `pip install pytest-timeout` and ensure your Python environment is correctly configured.
ValueError: Invalid timeout-method 'X'. Must be one of: 'thread', 'signal', 'process'.
An unrecognized or misspelled timeout method was specified in the configuration or command line.
fixUse a valid timeout method such as `thread`, `signal` (Unix-only), or `process` for `--timeout-method` or in `pytest.ini`.
pytest: warning: unknown pytest.mark.timeout marker (may require "--strict-markers" command line option)
The `pytest.mark.timeout` marker is not explicitly registered in your `pytest.ini` file, leading to a warning or the timeout not being applied.
fixRegister the marker by adding `markers = timeout` under the `[pytest]` section in your `pytest.ini` file, or ensure `pytest-timeout` is correctly installed.
ValueError: signal timeout-method only available on Unix.
The `signal` timeout method was specified on a non-Unix operating system, such as Windows, where POSIX signals are not available.
fixUse `timeout-method=thread` or `timeout-method=process` instead, as `signal` is only supported on Unix-like systems.
Upgrade
Version history
2.4.0latest on PyPI · released May 5, 2025
Audit
Dependencies
pytestrequiredCore testing framework that this plugin extends.