ghp-import

What it is and what it does

ghp-import takes a local documentation directory and commits it to the gh-pages branch with a single command or function call, solving the problem of managing a separate branch for GitHub Pages hosting. It wraps Git operations and provides both a CLI interface and a Python API, optionally pushing the branch to a remote repository, writing CNAME records, and adding .nojekyll files to disable Jekyll processing.

The package depends only on python-dateutil and runs as a pure-Python wheel, making installation straightforward. It treats the gh-pages branch as fully derivative—it will overwrite the branch's contents on each run unless a prefix is specified—so it assumes documentation is regenerated and re-imported as part of a build workflow rather than edited directly.

Use it for:

• Publish Sphinx documentation output to GitHub Pages as part of a build workflow.
• Deploy static site generator output to GitHub Pages without manual branch management.
• Set up custom domain hosting on GitHub Pages by writing CNAME records during deployment.
• Maintain a clean gh-pages history by using the no-history flag to avoid repository bloat.
• Deploy documentation to organization or user pages by specifying a different branch instead of gh-pages.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Automates publishing built documentation to GitHub Pages by managing the gh-pages branch, handling file synchronization, and optionally pushing changes to a remote repository.

Yes, if you need to automate GitHub Pages deployment and are comfortable with dormant maintenance status. The tool is stable and widely used (top 5000 on PyPI), has no known vulnerabilities, and low install friction. Verify compatibility with your current Git version and authentication setup before relying on it in a new CI/CD pipeline.

Install

ghp-import on PyPI

pip install ghp-import

uv add ghp-import

poetry add ghp-import

Installing ghp-import

Before you install

Low friction: single pure-Python wheel with one lightweight runtime dependency (python-dateutil). Maintenance is dormant—last release May 2022—but the repository remains active with 626 stars, suggesting the tool is stable enough that active development has ceased rather than stalled.

License in practice

Apache Software License (permissive) means you can use, modify, and distribute this package freely in commercial and private projects, with only the requirement to include a copy of the license and state any changes made.

Quickstart

pip install ghp-import

from ghp_import import ghp_import
ghp_import('docs', push=True, cname='example.com')

Requires Git to be installed and available on the system PATH; the package wraps Git commands to manage the gh-pages branch.

Verify before relying

• Whether the package works reliably with modern Git versions and GitHub's current authentication requirements (SSH keys, personal access tokens).
• Compatibility with recent Python versions beyond what classifiers indicate, given dormant maintenance status since 2022.

Package facts

Evidence: ghp_import-2.1.0-py3-none-any.whl

Tags

More Documentation packages