---
id: python-subunit
version: "1.4.6"
license: Apache-2.0 or BSD
license_treatment: permissive
maintenance: active
---

# python-subunit — Python implementation of subunit test streaming protocol

License: permissive · Maintenance: active · Downloads: 1.3M/mo

## What it is and what it does

Subunit is a Python implementation of a streaming protocol for test results designed to handle distributed, parallel, and cross-language test execution. It models xUnit-style test outcomes (start, pass/fail, finish) and extends them with test enumeration, tagging, file attachments, and timestamps. The protocol comes in two versions: Version 1 (human-readable but with buffering and corruption issues in parallel scenarios) and Version 2 (binary, packet-based, designed for multiplexing without excessive buffering and with recovery mechanisms for corrupted streams).

The package provides Python bindings to emit and consume subunit streams, making it useful for aggregating test results from separate processes, languages, or machines into a single unified stream. It includes filters and tools to convert between subunit and other formats (CSV, JUnit XML, TAP), and integrates with Python's unittest framework via the subunit.run module. Dependencies on iso8601, PyYAML, and testtools keep the core lightweight while supporting timestamp parsing, configuration, and test result modeling.

Use it for:

- Aggregate test results from multiple test runners or languages into a single stream for centralized reporting.
- Run isolated test suites in separate processes and combine their results without interference using subunit's multiplexing.
- Archive and replay test runs by recording subunit streams and replaying them later for analysis or debugging.
- Distribute test execution across multiple machines and collect results in real time via a subunit stream.
- Convert test results between formats (e.g., TAP to subunit, subunit to JUnit XML) using the protocol's filters.

## Worth the install?

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

Subunit is a streaming protocol library for test results that aggregates, serializes, and multiplexes test execution across languages and machines into a unified stream.

Yes. Subunit is actively maintained, has no known vulnerabilities, installs with low friction, and is licensed permissively. Install it if you need to aggregate, multiplex, or serialize test results across distributed or parallel test runs, or if you're integrating tests from multiple languages or frameworks. Skip it if your testing stays within a single process or framework without cross-language aggregation needs.

## Install

pip install python-subunit
uv add python-subunit
poetry add python-subunit

## Installing python-subunit

Before you install: Low friction install with a pure-Python wheel. Active maintenance with recent commits and support for current Python versions (3.10–3.14). Three lightweight runtime dependencies (iso8601, PyYAML, testtools) are all stable, widely-used libraries.

License in practice: Dual-licensed under Apache-2.0 or BSD (user's choice), both permissive licenses with no copyleft obligations. You may use, modify, and distribute freely under either license terms.

Quickstart:

pip install python-subunit

import subunit
from subunit import StreamResultToDict

# Parse a subunit stream
result_dict = StreamResultToDict()
# Feed stream data to result_dict and extract test results

Requires Python 3.10 or later; depends on iso8601, PyYAML, and testtools at runtime.

Verify before relying:

- Whether the package includes command-line filters (tap2subunit, subunit2csv, etc.) mentioned in the description or if those are separate tools.
- Whether GTK and JUnit XML conversion features are available in the Python bindings or require additional setup.
- Current state of protocol version 2 implementation and stability relative to version 1.

## Package facts

- License: Apache-2.0 or BSD (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.3M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

test result streaming protocol, test aggregation and multiplexing, distributed test reporting, xunit test serialization, parallel test result collection, cross-language test integration, test stream filtering and conversion, test-infrastructure, distributed-testing, protocol-implementation

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