pytest-threadleak

What it is and what it does

pytest-threadleak is a pytest plugin that automatically detects when a test leaves threads running after it completes. It works by checking for leaked threads after each test and failing the test if any are found. You can enable it globally via pytest.ini, per-test using the @pytest.mark.threadleak decorator, or per-module. The plugin also supports excluding specific threads by regex pattern if certain background threads are expected.

The plugin helps catch both test bugs (tests that spawn threads without cleaning them up) and issues in the code being tested (libraries that leak threads). It integrates seamlessly into your pytest workflow and requires no changes to test code beyond optionally adding markers or configuration.

Use it for:

• Catch tests that spawn background threads without properly joining or stopping them before test completion.
• Detect thread leaks in libraries under test that may cause resource exhaustion or test isolation problems.
• Enforce thread cleanup discipline across a test suite by enabling threadleak globally in pytest configuration.
• Exclude known background threads (e.g., connection pools) from leak detection using regex patterns.
• Debug test flakiness caused by threads from previous tests interfering with subsequent tests.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pytest plugin that detects when tests leak threads—threads that remain running after a test completes—and fails the test to surface the issue.

Yes, if you need to catch thread leaks in your tests. The plugin is simple, low-friction, and has no known vulnerabilities. However, be aware that maintenance is dormant; verify compatibility with your pytest and Python versions before relying on it in a critical pipeline. For most projects, the benefit of catching thread leaks outweighs the maintenance risk.

Install

pytest-threadleak on PyPI

pip install pytest-threadleak

uv add pytest-threadleak

poetry add pytest-threadleak

Installing pytest-threadleak

Before you install

Low install friction; depends only on pytest. Maintenance is dormant—last release was 2022-07-03, though the repository remains active and has not been archived.

License in practice

MIT license (permissive); you may use, modify, and distribute this software freely with minimal restrictions.

Quickstart

pip install pytest-threadleak

# In your test file or pytest.ini:
# pytest.ini:
# [pytest]
# threadleak = True

# Then run:
# pytest --threadleak your_test.py

Verify before relying

• Whether the plugin works correctly with modern pytest versions given the last release was 2022-07-03.
• Whether thread exclusion patterns (threadleak_exclude) work as documented with current Python threading internals.
• Performance impact when running large test suites with threadleak enabled.

Package facts

Evidence: pytest_threadleak-0.5.0-py3-none-any.whl

Tags

More Testing packages