Install & Compatibility
Where this runs
tested against v16.0.0 · 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.000s · 28.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.000s · 29MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Module
✓ from pdoc import Module
✗ from pdoc import Module
This quickstart demonstrates how to generate HTML documentation for a Python module programmatically using `pdoc.html()`. It creates a dummy module, generates its documentation, and saves it to an HTML file. The `pdoc` library is primarily used as a command-line tool, but offers a robust programmatic API. For CLI usage, simply run `pdoc your_module.py` or `pdoc your_package`.
import os
import sys
from pathlib import Path
# Create a dummy module for documentation
dummy_module_content = '''
"""A simple example module."""
class MyClass:
"""This is MyClass.
Attributes:
name (str): The name of the instance.
"""
def __init__(self, name: str):
self.name = name
def greet(self, loud: bool = False) -> str:
"""Greets the user.
Args:
loud (bool): If True, returns an uppercase greeting.
Returns:
str: The greeting message.
"""
message = f"Hello, {self.name}!"
return message.upper() if loud else message
def my_function(x: int, y: int) -> int:
"""Adds two numbers.
Args:
x (int): The first number.
y (int): The second number.
Returns:
int: The sum of x and y.
"""
return x + y
'''
# Create a temporary file for the dummy module
module_path = Path('./temp_my_module.py')
module_path.write_text(dummy_module_content)
# Add the current directory to sys.path to allow importing the temporary module
sys.path.insert(0, str(Path('.').resolve()))
# Generate documentation programmatically
try:
import temp_my_module
from pdoc import html
print("Generating documentation for temp_my_module...")
# Generate HTML documentation for the module
html_output = html(temp_my_module)
# Optionally write to a file
output_dir = Path('./pdoc_output')
output_dir.mkdir(exist_ok=True)
output_file = output_dir / 'temp_my_module.html'
output_file.write_text(html_output)
print(f"Documentation generated to {output_file.resolve()}")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up the temporary module file and sys.path
if module_path.exists():
module_path.unlink()
if str(Path('.').resolve()) in sys.path:
sys.path.remove(str(Path('.').resolve()))
# You can also run from the command line:
# pdoc ./temp_my_module.py
# or for a package:
# pdoc my_package --output-directory docs
pdoc --version
Debug
Known issues
breakingpdoc is the actively maintained original project. `pdoc3` is an unrelated fork with different features, maintainers, and licenses, and is not recommended by the official `pdoc` project. Ensure you are installing and using `pdoc` from PyPI (`pip install pdoc`).fixAlways install `pdoc` (not `pdoc3`) and refer to the official documentation at `pdoc.dev`.
affects: All versions (comparison between projects)
gotchaWhen `pdoc` imports your modules for documentation, any top-level executable code not protected by an `if __name__ == "__main__":` guard will run. This can cause unexpected side effects, errors (e.g., if code expects command-line arguments), or slow documentation generation.fixEncapsulate any module-level executable code within an `if __name__ == "__main__":` block to prevent it from running during import.
affects: All versions
gotchaThe current `pdoc` library primarily generates output in HTML format. If you require other formats (like PDF or Markdown for integration with static site generators that expect raw Markdown), you may need to look for external tools or alternative documentation generators.fixConsider `pdoc` for HTML-centric documentation. For other formats, evaluate tools like Sphinx or pandoc for conversion after HTML generation, or choose a different primary documentation generator.
affects: All current versions
gotchaFor `pdoc` to recognize a directory as a package and document its submodules, the directory must contain an `__init__.py` file (even if empty), following standard Python package conventions. Simply having Python files in a directory without `__init__.py` will not allow `pdoc` to traverse and document it as a package.fixEnsure all directories intended to be documented as Python packages contain an `__init__.py` file.
affects: All versions
deprecatedThe `__pdoc__` module-level dictionary (used to override docstrings or control visibility of members) was explicitly removed in `pdoc` 1.0.0 (January 2021) as 'rarely required'. However, recent documentation (pdoc 16.0.0) indicates it is now supported again for specific use cases like `namedtuple` or including private objects. There's historical confusion on this, so verify usage with the latest official `pdoc.dev` documentation.fixRefer to the current `pdoc.dev` documentation for the up-to-date behavior of `__pdoc__`. If you're using an older `pdoc` version that removed it, you may need to upgrade or adjust your documentation practices.
affects: Versions 1.0.0 to ~15.x.x (exact re-introduction version unclear), potentially confusing for users migrating from older versions or `pdoc3`.
Upgrade
Version history
16.0.0latest on PyPI · released Oct 27, 2025
Audit
Dependencies
No dependency data recorded yet.