Recommended Free Tools
Pytest’s core does not provide the timeout mechanism described here. Install the pytest-timeout plugin, then set a default with pytest --timeout=30 or the plugin’s timeout configuration setting. To give one test a different limit, use @pytest.mark.timeout(5). These limits are in seconds and are intended to stop hangs, not measure performance precisely. pytest-timeout documentation
Install pytest-timeout and set a default
Install the plugin in the same Python environment used to run your tests:
python -m pip install pytest-timeout
pytest --timeout=30The number is a limit in seconds. The example uses 30 seconds as an illustration, not as a universal recommendation; choose a limit that fits the expected runtime and environment of your tests. Pytest automatically discovers installed plugins.
To apply a default to the project, add this to a pytest configuration file using the INI-style syntax shown:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
[pytest]
timeout = 30Pytest supports several configuration-file formats. Keep the setting in the format already used by your project, following that format’s corresponding pytest configuration syntax.
Set a timeout for one test
Use the plugin’s marker to override the default for an individual test:
import pytest
@pytest.mark.timeout(5)
def test_may_hang():
...The marker takes seconds. A value of zero disables the timeout for that item. The plugin’s documented precedence is configuration setting, PYTEST_TIMEOUT environment variable, command-line option, then item marker; a marker can therefore set a test-specific value over the configured defaults.
Understand what the timeout covers
By default, the timeout covers test setup, execution, and relevant finalizers. This means time spent in fixtures can count toward the limit, not just the lines inside the test function. If fixture setup is intentionally slow and you want to limit only the test body, set timeout_func_only in configuration or pass func_only=True to the marker:
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match[pytest]
timeout = 30
timeout_func_only = true@pytest.mark.timeout(5, func_only=True)
def test_may_hang():
...Use function-only timing deliberately: it excludes setup time from the test’s timeout, so a hang during fixture setup will not be caught by that per-test limit.
Choose how pytest handles a timeout
pytest-timeout offers signal and thread methods. Set the method through configuration, a command-line option, or a marker, as supported by the installed plugin version.
| Method | Behavior and trade-off |
|---|---|
signal |
Uses SIGALRM where supported and is the default on POSIX systems that support it. It can interrupt the test and allow pytest to continue, but may conflict with application or test code that also uses SIGALRM. |
thread |
More portable and the documented safer choice when the plugin is not called from the main thread. A timeout can terminate the whole process, which may prevent normal fixture teardown and JUnit XML output. |
Neither method guarantees graceful recovery in every case. Select based on your platform and whether continuing the test process matters; check the plugin documentation for the exact option syntax supported by your installed version.
Use a session timeout only for suite-level limits
The plugin also supports --session-timeout and session_timeout. This checks the overall expiration between tests; it does not interrupt a test that is currently running. Use a per-test timeout when the goal is to guard against one test hanging.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Troubleshoot common timeout problems
- The option or marker is unknown: confirm
pytest-timeoutis installed in the environment that runs pytest, then check the installed plugin version’s documentation for supported settings. - A fixture setup hang is not stopped: check whether
timeout_func_onlyorfunc_only=Truenarrows the timeout to the test function body. Remove that narrowing if setup should be covered. - The whole test run exits after a timeout: this can happen with the
threadmethod, which may terminate the process. If your environment supports it and your code does not useSIGALRM, consider whethersignalbetter fits your needs. - Timeout handling conflicts with application code: check whether that code uses
SIGALRM; the signal method may conflict with it. Consider the thread method while accounting for its process-termination consequences. - The suite limit does not stop a slow current test: that is expected for a session timeout, which is checked between tests. Add a per-test timeout for individual hangs.
Keep timeout limits in perspective
The plugin describes timeouts as a last resort for excessively long or deadlocked tests, not a tool for precise timing or performance regressions. For performance tracking, use a measurement approach designed for that purpose rather than treating a timeout threshold as a benchmark. Timeout behavior and available options can change between plugin releases, so verify details against the version installed in your environment.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers, unrelated to configuring pytest timeouts. If you also need to capture web pages from code, one GET request can return an image or PDF. See the ScreenshotNeo API documentation.
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpIt removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
