Install & Compatibility
Where this runs
tested against v0.11.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.498s · 21.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.426s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pdoc
✓ import pdoc
✗ import pdoc3
The PyPI package is 'pdoc3', but the primary module for programmatic use is named 'pdoc'.
This quickstart demonstrates how to generate HTML documentation for a simple Python module using pdoc3 programmatically. It creates a temporary Python file, generates docs into a 'docs/' directory, and then cleans up the temporary file. For command-line usage, simply run `pdoc your_module_or_package`.
import pdoc
import os
# Create a dummy module file for documentation
dummy_module_content = """
\"\"\"
A simple example module.
\"\"\"
class MyClass:
\"\"\"
A sample class.
Attributes:
name (str): The name of the instance.
\"\"\"
def __init__(self, name: str):
self.name = name
def greet(self) -> str:
\"\"\"
Greets the user.
\"\"\"
return f"Hello, {self.name}!"
def my_function(value: int) -> int:
\"\"\"
A sample function.
Args:
value (int): An integer input.
Returns:
int: The input value multiplied by 2.
\"\"\"
return value * 2
"""
with open("my_example_module.py", "w") as f:
f.write(dummy_module_content)
# Generate documentation for the module
# Output to a 'docs' directory
pdoc.pdoc("my_example_module", output_directory="docs")
print("Documentation generated in 'docs/' directory.")
print("You can view it by opening docs/my_example_module.html")
# Clean up the dummy module file
os.remove("my_example_module.py")
# To clean up the generated documentation directory:
# import shutil
# shutil.rmtree("docs")
pdoc3 --version
Debug
Known issues
breakingpdoc3 is a fork of the original `pdoc` and is exclusively for Python 3.9+. Older Python 2 or earlier Python 3 projects will not be compatible. The `0.5.0` release marked a major refactoring for Python 3 compatibility.fixEnsure your project runs on Python 3.9+ and use `pdoc3`. If targeting older Python versions, consider the legacy `pdoc` releases or other documentation tools.
affects: <0.5.0 (pdoc compatibility)
gotchaThe `pdoc` and `pdoc3` projects have diverged. Features like the `__pdoc__` module-level dictionary (used to override or exclude docstrings) are supported in `pdoc3` but were removed from the original `pdoc` in its 1.0.0 release. Consult the correct project's documentation.fixAlways refer to the official `pdoc3` documentation for current features. If migrating, check for feature parity or changes.
affects: All versions
gotchaUsers frequently encounter `ValueError: File or module not found` or `ImportError` if the Python modules or packages to be documented are not correctly discoverable in the Python path (`PYTHONPATH`) or current working directory.fixEnsure the directory containing your module/package is in your `PYTHONPATH` environment variable or run `pdoc` from the parent directory of your module/package.
affects: All versions
breakingSince version `0.6.0`, `__init__` methods are no longer documented separately. Their docstrings are merged into the class docstring, and constructor parameters are displayed on the class definition line, aligning with Sphinx/Python stdlib documentation conventions.fixAdjust documentation expectations; class-level docstrings should now include `__init__` documentation. If you relied on separate `__init__` documentation, you may need to refactor docstrings.
affects: >=0.6.0
gotchaThe `--skip-errors` flag might not function as expected in `pdoc3` versions prior to `0.11.2`, leading to documentation generation failures even when errors should be skipped.fixUpgrade to `pdoc3` version `0.11.2` or newer to ensure `--skip-errors` works reliably. Alternatively, ensure all modules are error-free.
affects: <0.11.2
Errors
Common errors & fixes
bash: pdoc: command not found
The `pdoc` executable, installed by `pip install pdoc3`, is not found in your system's PATH environment variable.
fixRun `pdoc3` using `python -m pdoc your_module` or ensure that your Python scripts directory (e.g., `~/.local/bin` or `C:\PythonXX\Scripts`) is added to your system's PATH.
ModuleNotFoundError: No module named 'your_module'
pdoc3 cannot find the specified Python module or package because it's not in Python's import path (sys.path) or the current working directory is not the parent of the module/package.
fixNavigate to the parent directory of the module/package you wish to document and run `pdoc3 your_module_name` or add the relevant directory to your `PYTHONPATH` environment variable.
ValueError: File or module 'xxx' not found
pdoc3 failed to locate the specified Python file or module, often due to an incorrect path, an uninstalled package, or a missing `__init__.py` in a directory when trying to document a package.
fixEnsure the module or file path is correct, the module is installable/importable from the environment where pdoc3 is run, and that packages have proper `__init__.py` files if they are not implicit namespace packages. Consider running `pdoc3 --html .` from your project's root for easier discovery.
ImportError: cannot import name 'escape' from 'jinja2'
This error occurs due to an incompatibility between your installed pdoc3 version and a newer version of the Jinja2 templating engine, as Jinja2 moved or removed the `escape` import in recent updates.
fixDowngrade Jinja2 to a compatible version (e.g., `pip install 'Jinja2<3.1'`) or upgrade pdoc3 to its latest version, which might have updated its Jinja2 dependency handling (`pip install --upgrade pdoc3`).
AttributeError: module 'pdoc' has no attribute 'pdoc'
This typically happens when attempting to use programmatic APIs (`pdoc.pdoc(...)`) intended for the older `pdoc` library, while `pdoc3` is installed, which has a different programmatic interface.
fixFor programmatic usage with pdoc3, you generally work with `pdoc.Module` objects and then call methods like `pdoc.html()` or `pdoc.text()` on them. The standard command-line usage `pdoc3 <module_name>` is usually sufficient.
Upgrade
Version history
0.11.6latest on PyPI · released Mar 20, 2025
Audit
Dependencies
PythonrequiredRequires Python 3.9 or newer.