How to Install `pytest-xdist` in Python

v3.8.0 Testing & QA Python >=3.9

pytest xdist plugin for distributed testing, most importantly across multiple CPUs

Install pip install pytest-xdist

What is pytest-xdist?

pytest xdist plugin for distributed testing, most importantly across multiple CPUs

The plugin extends pytest with new test execution modes, the most used being distributing tests across multiple CPUs to speed up test execution::

With this call, pytest will spawn a number of workers processes equal to the number of available CPUs, and distribute the tests randomly across them.

PyPI page → Author: holger krekel and contributors <pytest-dev@python.org>, holger@merlinux.eu

Quick Start

Minimal example to get started with pytest-xdist:

import pytest_xdist

print(pytest_xdist.__version__)

Installation

pip (standard)

pip install pytest-xdist

Virtual environment (recommended)

python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install pytest-xdist

pip3

pip3 install pytest-xdist

conda

conda install -c conda-forge pytest-xdist

Poetry

poetry add pytest-xdist

Dependencies

Installing pytest-xdist will also install these packages:

execnet pytest

Verify the Installation

After installing, confirm the package is available:

python -c "import pytest_xdist; print(pytest_xdist.__version__)"

If this prints a version number, installation succeeded. If you see a ModuleNotFoundError, see the errors section below.

Installation Errors

Common errors when installing pytest-xdist with pip.

ModuleNotFoundError: No module named 'pytest_xdist'

Cause: The package is not installed in the current Python environment.

Fix: Run pip install pytest-xdist. If using a virtual environment, ensure it is activated first.

ModuleNotFoundError: No module named 'pytest_xdist' (installed but still failing)

Cause: pip installed the package into a different Python than the one running your script.

Fix: Use python -m pip install pytest-xdist to install into the interpreter you are running.

ImportError: cannot import name 'X' from 'pytest_xdist'

Cause: The function or class does not exist in the installed version.

Fix: Check the version with pip show pytest-xdist and upgrade with pip install --upgrade pytest-xdist.

pip: command not found

Cause: pip is not in PATH or Python was not added to PATH during installation.

Fix: Try python -m pip install pytest-xdist. On macOS/Linux try pip3.

PermissionError: [Errno 13] Permission denied

Cause: No write access to the system Python package directory.

Fix: Use a virtual environment, or add --user: pip install --user pytest-xdist

SSL: CERTIFICATE_VERIFY_FAILED

Cause: pip cannot verify PyPI's SSL certificate — common behind corporate proxies.

Fix: Try: pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org pytest-xdist

Recent Releases

Version	Released
`3.8.0` latest	2025-07-01
`3.7.0`	2025-05-26
`3.6.1`	2024-04-28
`3.6.0`	2024-04-19
`3.5.0`	2023-11-21

Full release history on PyPI →

Manage pytest-xdist

Upgrade to latest version

pip install --upgrade pytest-xdist

Install a specific version

pip install pytest-xdist==3.8.0

Uninstall

pip uninstall pytest-xdist

Check what is installed

pip show pytest-xdist

Last updated: 2026-04-11 • Data from PyPI

How to Install pytest-xdist in Python