---
id: pytest-shard
version: "0.1.2"
license: MIT
license_treatment: permissive
maintenance: abandoned
---

# pytest-shard

License: permissive · Maintenance: abandoned · Downloads: 1.8M/mo

## What it is and what it does

pytest-shard is a pytest plugin that divides your test suite across multiple CI workers or machines by hashing individual test names and assigning each test to a shard. It works at the finest granularity—individual test cases—so even a single parameterized test or file can be split across workers. You run pytest with two flags: --shard-id (which worker this is) and --num-shards (total number of workers), and the plugin automatically routes each test to its assigned shard.

The package is designed for continuous integration pipelines that support parallel jobs, such as CircleCI or Travis CI. It does not balance based on test runtime—all shards receive roughly equal numbers of tests—and is meant to complement tools like pytest-xdist, which parallelizes across CPU cores on a single machine. The package is no longer maintained; its last release was in December 2020.

Use it for:

- Split a large test suite across multiple CircleCI workers using CIRCLE_NODE_INDEX and CIRCLE_NODE_TOTAL environment variables.
- Parallelize test execution on Travis CI by distributing test cases across multiple build jobs.
- Reduce total CI build time by running disjoint test shards on separate machines without test interdependencies.
- Enable fine-grained parallelism even when all tests live in a single file or parameterized test method.

## Worth the install?

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

Distributes pytest test execution across multiple machines or CI workers by sharding individual test cases based on a hash of their names, enabling parallel test runs without requiring shared state.

Yes, if you are running pytest on a CI platform that supports parallel jobs and your test suite is stable. The plugin is simple and has no known vulnerabilities. However, do not adopt it for new projects: the package is abandoned and will not receive updates for future pytest or Python versions. Consider it only if you have an existing CI setup that already uses it or if you can commit to maintaining a fork.

## Install

pip install pytest-shard
uv add pytest-shard
poetry add pytest-shard

## Installing pytest-shard

Before you install: Low install friction with a single runtime dependency on pytest. However, the package is abandoned—last release was 2020-12-11 and no commits since 2023-08-22—so it will not receive bug fixes or compatibility updates for future Python or pytest versions.

License in practice: MIT license is permissive and imposes no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart:

pip install pytest-shard

pytest --shard-id=0 --num-shards=2

Requires pytest to be installed; intended for CI environments that can set shard-id and num-shards parameters.

Verify before relying:

- Whether the package remains compatible with current pytest versions and modern Python releases beyond 3.8
- Whether hash-based sharding produces balanced test distribution across workers in practice

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: abandoned
- Downloads: 1.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest parallel ci workers, distribute tests across machines, pytest test sharding, ci test parallelization, pytest load balancing, split tests multiple workers, pytest horizontal scaling, ci-parallelization, test-distribution

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