pytest-timeout
raw JSON → 2.4.0 verified Tue May 12 auth: no python install: verified quickstart: verified
pytest-timeout is an actively maintained pytest plugin designed to automatically abort excessively long-running or hanging tests. It helps in maintaining efficient test suites by enforcing timeout limits at various levels (global, session, per-test) and provides different methods to terminate tests. The current version is 2.4.0 and it is part of the pytest-dev organization, implying regular updates and maintenance.
pip install pytest-timeout Common errors
error pytest: error: unrecognized arguments: --timeout=X ↓
cause The `pytest-timeout` plugin is not installed or pytest cannot find it, so the `--timeout` command-line argument is not recognized.
fix
Install the plugin using
pip install pytest-timeout and ensure your Python environment is correctly configured. error ValueError: Invalid timeout-method 'X'. Must be one of: 'thread', 'signal', 'process'. ↓
cause An unrecognized or misspelled timeout method was specified in the configuration or command line.
fix
Use a valid timeout method such as
thread, signal (Unix-only), or process for --timeout-method or in pytest.ini. error pytest: warning: unknown pytest.mark.timeout marker (may require "--strict-markers" command line option) ↓
cause The `pytest.mark.timeout` marker is not explicitly registered in your `pytest.ini` file, leading to a warning or the timeout not being applied.
fix
Register the marker by adding
markers = timeout under the [pytest] section in your pytest.ini file, or ensure pytest-timeout is correctly installed. error ValueError: signal timeout-method only available on Unix. ↓
cause The `signal` timeout method was specified on a non-Unix operating system, such as Windows, where POSIX signals are not available.
fix
Use
timeout-method=thread or timeout-method=process instead, as signal is only supported on Unix-like systems. Warnings
breaking Minimum `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. ↓
fix Upgrade pytest to `pytest>=7.0.0` using `pip install --upgrade pytest` and ensure Python is 3.7 or newer.
gotcha The 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. ↓
fix If 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.
gotcha Session 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. ↓
fix For 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`.
gotcha By 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. ↓
fix If 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.
gotcha By 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. ↓
fix If 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`.
gotcha The 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`. ↓
fix To 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`.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.43s 30.7M
3.10 alpine (musl) - - 0.46s 30.5M
3.10 slim (glibc) wheel 2.8s 0.30s 31M
3.10 slim (glibc) - - 0.31s 31M
3.11 alpine (musl) wheel - 0.55s 33.6M
3.11 alpine (musl) - - 0.61s 33.4M
3.11 slim (glibc) wheel 2.6s 0.53s 34M
3.11 slim (glibc) - - 0.48s 34M
3.12 alpine (musl) wheel - 0.52s 25.2M
3.12 alpine (musl) - - 0.53s 25.0M
3.12 slim (glibc) wheel 2.5s 0.49s 26M
3.12 slim (glibc) - - 0.56s 25M
3.13 alpine (musl) wheel - 0.45s 25.0M
3.13 alpine (musl) - - 0.47s 24.7M
3.13 slim (glibc) wheel 2.5s 0.43s 25M
3.13 slim (glibc) - - 0.57s 25M
3.9 alpine (musl) wheel - 0.36s 30.0M
3.9 alpine (musl) - - 0.39s 29.8M
3.9 slim (glibc) wheel 3.1s 0.35s 31M
3.9 slim (glibc) - - 0.32s 30M
Imports
- pytest.mark.timeout
import pytest @pytest.mark.timeout(300) def test_example(): pass
Quickstart verified last tested: 2026-04-24
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)