{"id":4215,"library":"pytest-shard","title":"pytest-shard","description":"pytest-shard is a pytest plugin (version 0.1.2) designed to parallelize test execution across multiple machines by sharding tests based on a hash of their test names. It enables fine-grained parallelism at the individual test case level, making it suitable for various continuous integration (CI) services. The library appears to be in a maintenance phase, with the last PyPI update in December 2020.","status":"maintenance","version":"0.1.2","language":"en","source_language":"en","source_url":"https://github.com/AdamGleave/pytest-shard","tags":["pytest","testing","parallelization","ci","continuous-integration","plugin"],"install":[{"cmd":"pip install pytest-shard","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core testing framework that pytest-shard extends as a plugin.","package":"pytest","optional":false}],"imports":[{"note":"pytest-shard integrates as a plugin and is enabled via command-line arguments to pytest, rather than explicit Python import statements in test files.","symbol":"pytest-shard plugin","correct":"No direct Python import needed; it's a pytest plugin automatically discovered."}],"quickstart":{"code":"# Example: Shard tests across two machines\n# On machine 1:\npytest --shard-id=0 --num-shards=2\n\n# On machine 2:\npytest --shard-id=1 --num-shards=2\n\n# Example for CircleCI:\npytest --shard-id=${CIRCLE_NODE_INDEX} --num-shards=${CIRCLE_NODE_TOTAL}","lang":"bash","description":"After installation, pytest-shard is enabled by passing `--shard-id` and `--num-shards` arguments to the `pytest` command. `--shard-id` specifies the index of the current shard (0-indexed), and `--num-shards` specifies the total number of shards. This is typically configured in CI pipelines where tests are distributed across parallel jobs."},"warnings":[{"fix":"Manually balance test durations across files/modules if even time distribution is critical. Consider alternative sharding mechanisms or CI-specific tools that track test durations for more sophisticated load balancing.","message":"pytest-shard does not take into account the run time of tests when sharding, which can lead to suboptimal load balancing and uneven test execution times across shards. This may result in some CI jobs finishing significantly later than others, despite an even numerical distribution of tests.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware that test renames will re-shard tests. If consistent sharding across minor changes is critical, consider using more stable test identifiers or a different sharding strategy. Avoid frequent, large-scale renames without understanding the impact on sharding.","message":"Sharding is based on a hash of the test name. Renaming tests or significantly changing their structure can alter their hash, causing them to move to a different shard. This can lead to unexpected test distribution changes in CI, potentially causing certain tests to be rerun on different machines or requiring manual re-evaluation of shard contents.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure CI environment variables providing the shard index are 0-based. If a variable is 1-based (e.g., `TRAVIS_JOB_NUMBER`), adjust it (e.g., `--shard-id=$((${TRAVIS_JOB_NUMBER} - 1))`) when passing to pytest.","message":"The `--shard-id` command-line option in pytest-shard is 0-indexed (e.g., `--shard-id=0` for the first shard). Users configuring CI environments should ensure their environment variables (like `CIRCLE_NODE_INDEX` or `TRAVIS_JOB_NUMBER`) are correctly mapped to this 0-indexed scheme to avoid skipping shards or encountering out-of-bounds errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}