---
id: pytest-split-tests
version: "1.1.0"
license: unclear
license_treatment: permissive
maintenance: dormant
---

# pytest-split-tests — A Pytest plugin for running a subset of your tests by splitting them in to equally sized groups. Forked from Mark Adams' original project pytest-test-groups.

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

## What it is and what it does

pytest-split-tests is a pytest plugin that partitions your test suite into equally-sized groups and lets you run a specific group. It's designed to solve the problem of long-running test jobs in CI by allowing you to distribute test execution across parallel workers—each worker runs a different group, reducing total wall-clock time.

The plugin adds command-line flags to pytest: --test-group-count sets the number of groups, --test-group selects which group to run, and --test-group-random-seed optionally assigns tests pseudo-randomly instead of sequentially. It depends only on pytest, making it lightweight to add to existing test infrastructure.

Use it for:

- Distribute a large test suite across multiple CI workers to reduce build time.
- Run a specific subset of tests locally for faster feedback during development.
- Balance test load across parallel jobs when test execution time varies widely.
- Integrate into CI pipelines (GitHub Actions, GitLab CI, etc.) to parallelize test stages.

## Worth the install?

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

A pytest plugin that splits your test suite into equal-sized groups so you can run a specific group in parallel or distributed CI environments.

Yes, if you need to parallelize tests in CI and are comfortable with dormant maintenance. The plugin is simple, has no known vulnerabilities, and low install friction. However, be aware that it has not been updated since 2021 and may not work reliably with pytest or Python versions released after that date—verify compatibility with your environment before relying on it in production.

## Install

pip install pytest-split-tests
uv add pytest-split-tests
poetry add pytest-split-tests

## Installing pytest-split-tests

Before you install: Low install friction; depends only on pytest. Maintenance is dormant—last release was 2021-07-30 and no commits since 2024-07-30—so expect no active bug fixes or feature updates, though the package remains archived=false.

License in practice: MIT license (permissive); you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart:

pip install pytest-split-tests

# In your CI or local shell:
py.test --test-group-count 10 --test-group=2

Verify before relying:

- Whether the plugin works with pytest versions released after 2021-07-30 without issues.
- Compatibility with modern Python versions beyond 3.9 (classifiers list only up to 3.9).

## Package facts

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

## Tags

pytest parallel test groups, split tests into groups, pytest distributed testing, ci test parallelization, pytest subset runner, test group splitting, ci-parallelization, pytest-plugin

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