---
id: xdoctest
version: "1.3.2"
license: Apache 2
license_treatment: permissive
maintenance: active
---

# xdoctest — A rewrite of the builtin doctest module

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

## What it is and what it does

Xdoctest is a replacement for Python's built-in doctest module that discovers and executes example code written in docstrings. Instead of using regex-based parsing, it employs an abstract-syntax-tree parser for more reliable detection and execution of doctests. The package encourages writing tests and documentation together in the same file, reducing boilerplate and helping developers maintain minimal working examples alongside their code.

You can run xdoctest either as a standalone command-line tool or as a pytest plugin. The standalone interface lets you execute all doctests in a module, list them, dump them as unit tests, or run specific functions' doctests. The pytest integration allows you to run doctests alongside your regular unit tests using a single command, making it practical for CI pipelines. The package is actively maintained, supports Python 3.8 through 3.14, and has no external runtime dependencies.

Use it for:

- Validate example code in function and class docstrings during development or CI to catch documentation drift
- Write minimal working examples in docstrings that serve as both documentation and regression tests
- Run all doctests in a project with a single command to ensure examples remain executable
- Integrate doctest execution into pytest workflows alongside unit tests for comprehensive test coverage
- Debug functions by first writing example inputs and outputs in docstrings, then implementing the body

## Worth the install?

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

Xdoctest finds and executes test code embedded in Python docstrings, replacing the built-in doctest module with an AST-based parser that integrates with pytest or runs standalone.

Yes. Xdoctest is a mature, actively maintained tool with zero dependencies and broad Python support. It solves a real problem—keeping documentation examples in sync with code—and integrates cleanly into both standalone and pytest workflows. The permissive Apache 2 license poses no restriction. Install it if you want to treat docstring examples as executable tests.

## Install

pip install xdoctest
uv add xdoctest
poetry add xdoctest

## Installing xdoctest

Before you install: Installation is straightforward with no runtime dependencies. The package is actively maintained, with a recent release and ongoing commits. It supports modern Python versions (3.8+) across CPython and PyPy implementations.

License in practice: Apache 2 is a permissive license, allowing use in most commercial and open-source projects without significant restriction.

Quickstart:

pip install xdoctest

# Run all doctests in a module
python -m xdoctest /path/to/module.py all

# Or with pytest
pytest --xdoctest /path/to/module.py

Requires Python 3.8 or later; Python 2.7 and 3.4–3.7 are no longer supported as of version 1.1.0 and 1.2.0 respectively.

Verify before relying:

- Performance characteristics when running doctests on large codebases or deeply nested modules
- Specific AST parsing edge cases or limitations compared to the built-in doctest module
- Compatibility with all pytest plugins or configurations

## Package facts

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

## Tags

doctest runner, execute doctests, docstring tests, pytest doctest plugin, documentation testing, example code validation, inline code examples, doctest, pytest-plugin, documentation-testing

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