# pytest-timeout > pytest plugin to abort hanging tests - **URL**: https://www.freshcrate.ai/projects/pytest-timeout - **Author**: Floris Bruynooghe - **Category**: Frameworks - **Latest version**: `2.4.0` (2026-04-21) - **License**: MIT - **Source**: https://github.com/pytest-dev/pytest-timeout - **Language**: Python - **GitHub**: 249 stars, 63 forks - **Registry**: pypi (`pytest-timeout`) - **Tags**: `pypi` ## Description ============== pytest-timeout ============== |python| |version| |anaconda| |ci| |pre-commit| .. |version| image:: https://img.shields.io/pypi/v/pytest-timeout.svg :target: https://pypi.python.org/pypi/pytest-timeout .. |anaconda| image:: https://img.shields.io/conda/vn/conda-forge/pytest-timeout.svg :target: https://anaconda.org/conda-forge/pytest-timeout .. |ci| image:: https://github.com/pytest-dev/pytest-timeout/workflows/build/badge.svg :target: https://github.com/pytest-dev/pytest-timeout/actions .. |python| image:: https://img.shields.io/pypi/pyversions/pytest-timeout.svg :target: https://pypi.python.org/pypi/pytest-timeout/ .. |pre-commit| image:: https://results.pre-commit.ci/badge/github/pytest-dev/pytest-timeout/master.svg :target: https://results.pre-commit.ci/latest/github/pytest-dev/pytest-timeout/master .. warning:: Please read this README carefully and only use this plugin if you understand the consequences. This plugin is designed to catch excessively long test durations like deadlocked or hanging tests, it is not designed for precise timings or performance regressions. Remember your test suite should aim to be **fast**, with timeouts being a last resort, not an expected failure mode. This plugin will time each test and terminate it when it takes too long. Termination may or may not be graceful, please see below, but when aborting it will show a stack dump of all thread running at the time. This is useful when running tests under a continuous integration server or simply if you don't know why the test suite hangs. .. note:: While by default on POSIX systems pytest will continue to execute the tests after a test has timed out this is not always possible. Often the only sure way to interrupt a hanging test is by terminating the entire process. As this is a hard termination (``os._exit()``) it will result in no teardown, JUnit XML output etc. But the plugin will ensure you will have the debugging output on stderr nevertheless, which is the most important part at this stage. See below for detailed information on the timeout methods and their side-effects. The pytest-timeout plugin has been tested on Python 3.6 and higher, including PyPy3. See tox.ini for currently tested versions. Usage ===== Install is as simple as e.g.:: pip install pytest-timeout Now you can run the test suite while setting a timeout in seconds, any individual test which takes longer than the given duration will be terminated:: pytest --timeout=300 Furthermore you can also use a decorator to set the timeout for an individual test. If combined with the ``--timeout`` flag this will override the timeout for this individual test: .. code:: python @pytest.mark.timeout(60) def test_foo(): pass By default the plugin will not time out any tests, you must specify a valid timeout for the plugin to interrupt long-running tests. A timeout is always specified as a number of seconds, and can be defined in a number of ways, from low to high priority: 1. You can set a global timeout in the `pytest configuration file`__ using the ``timeout`` option. E.g.: .. code:: ini [pytest] timeout = 300 2. The ``PYTEST_TIMEOUT`` environment variable sets a global timeout overriding a possible value in the configuration file. 3. The ``--timeout`` command line option sets a global timeout overriding both the environment variable and configuration option. 4. Using the ``timeout`` marker_ on test items you can specify timeouts on a per-item basis: .. code:: python @pytest.mark.timeout(300) def test_foo(): pass __ https://docs.pytest.org/en/latest/reference.html#ini-options-ref .. _marker: https://docs.pytest.org/en/latest/mark.html Setting a timeout to 0 seconds disables the timeout, so if you have a global timeout set you can still disable the timeout by using the mark. Timeout Methods =============== Interrupting tests which hang is not always as simple and can be platform dependent. Furthermore some methods of terminating a test might conflict with the code under test itself. The pytest-timeout plugin tries to pick the most suitable method based on your platform, but occasionally you may need to specify a specific timeout method explicitly. If a timeout method does not work your safest bet is to use the *thread* method. thread ------ This is the surest and most portable method. It is also the default on systems not supporting the *signal* method. For each test item the pytest-timeout plugin starts a timer thread which will terminate the whole process after the specified timeout. When a test item finishes this timer thread is cancelled and the test run continues. The downsides of this method are that there is a relatively large overhead for running each test and that test runs are not completed. This means that other pytest features, like e.g. JUnit XML output or fixture ## Recent releases | Version | Date | Urgency | Changes | | --- | --- | --- | --- | | `2.4.0` | 2026-04-21 | Low | Imported from PyPI (2.4.0) | | `main@2026-01-13` | 2026-01-13 | Low | Latest activity on main branch | | `main@2026-01-13` | 2026-01-13 | Low | Latest activity on main branch | | `main@2026-01-13` | 2026-01-13 | Low | Latest activity on main branch | | `main@2026-01-13` | 2026-01-13 | Low | Latest activity on main branch | | `main@2026-01-13` | 2026-01-13 | Low | Latest activity on main branch | | `main@2026-01-13` | 2026-01-13 | Low | Latest activity on main branch | | `main@2026-01-13` | 2026-01-13 | Low | Latest activity on main branch | | `main@2026-01-13` | 2026-01-13 | Low | Latest activity on main branch | | `main@2026-01-13` | 2026-01-13 | Low | Latest activity on main branch | ## Citation - HTML: https://www.freshcrate.ai/projects/pytest-timeout - Markdown: https://www.freshcrate.ai/projects/pytest-timeout.md - Dependencies JSON: https://www.freshcrate.ai/api/projects/pytest-timeout/deps _Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._