---
id: stestr
version: "4.2.1"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# stestr — A parallel Python test runner built around subunit

License: permissive · Maintenance: active · Downloads: 202.5K/mo

## What it is and what it does

stestr is a dedicated test runner for Python projects that executes unittest test suites in parallel across multiple processes to reduce overall test time. It originated as a fork of testrepository but is now a standalone tool focused specifically on Python testing. The runner uses the subunit protocol to stream and aggregate results from multiple workers, and maintains a persistent repository of test run history to help with debugging failures and optimizing test scheduling.

You configure stestr with a .stestr.conf file (or a stestr section in tox.ini) that specifies where tests are located, then invoke stestr run to execute them. The tool handles test discovery, parallel distribution, result collection, and storage automatically. It stores results in a .stestr/ directory in your working directory, allowing you to inspect past runs and compare performance across test cycles.

Use it for:

- Speed up CI/CD pipelines by running large unittest suites in parallel across available CPU cores.
- Debug intermittent test failures by replaying specific test runs from the stored history.
- Migrate from testrepository to a modern, actively maintained test runner without rewriting test code.
- Track test performance trends over time by analyzing the persistent repository of run results.
- Run individual tests or modules without discovery overhead using the --no-discover flag.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

stestr is a parallel test runner for Python unittest suites that distributes test execution across multiple processes and maintains a history of test runs using the subunit protocol.

Yes. stestr is actively maintained, has low install friction, carries a permissive license, and solves a real problem—parallel test execution with result history—for Python projects using unittest. It supports modern Python versions and has no known vulnerabilities. Install it if your project runs unittest suites and would benefit from faster parallel execution or historical test analysis.

## Install

pip install stestr
uv add stestr
poetry add stestr

## Installing stestr

Before you install: Low install friction with a pure-Python wheel distribution. Active maintenance with a recent release and ongoing commits; supports current Python versions from 3.8 through 3.14.

License in practice: Apache-2.0 permissive license allows use in most projects, including proprietary software, with minimal restrictions.

Quickstart:

pip install stestr

Create .stestr.conf:
[DEFAULT]
test_path=./tests

Then run: stestr run

Requires Python 3.8 or later; project must have unittest-compatible tests discoverable from a configured path.

Verify before relying:

- Whether stestr's parallel scheduling strategies are documented or tunable for specific workload patterns.
- Performance characteristics when running very large test suites or with many worker processes.
- Integration depth with CI/CD systems beyond tox.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 202.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

parallel python test runner, unittest parallel execution, distributed test runner, subunit test framework, python test orchestration, multi-process test execution, test result history tracking, parallel-testing, test-orchestration, unittest

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