---
id: pytest-threadleak
version: "0.5.0"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# pytest-threadleak — Detects thread leaks

License: permissive · Maintenance: dormant · Downloads: 240.7K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: dormant
- Downloads: 240.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest thread leak detection, detect leaking threads in tests, pytest plugin thread cleanup, thread leak testing, pytest thread monitoring, test thread validation, pytest thread safety check, pytest-plugin, thread-safety, test-quality

[View on SkillFed](https://skillfed.io/packages/pytest-threadleak) · [View on PyPI](https://pypi.org/project/pytest-threadleak/)