ghp-import is a lightweight Python package designed to simplify the deployment of static content to GitHub Pages. It automates the process of copying built documentation or other static files to the `gh-pages` branch of a GitHub repository, then committing and pushing them. The current version is 2.1.0, and it has an infrequent but active release cadence, with the last major release in May 2022.
pip install ghp-importVerified import paths — ran on the pinned version, not inferred.
The most common way to use ghp-import is as a command-line tool, pointing it to your generated static files. The example shows how to deploy a 'docs_output' directory to the 'gh-pages' branch, automatically add a '.nojekyll' file (to prevent Jekyll processing), and push to the remote. It also includes a Python programmatic example for more advanced integration.
Always treat your `gh-pages` branch as entirely generated by ghp-import. Do not make manual edits directly on this branch. If you need to include static assets not generated by your build process, place them within your source directory and ensure your build process copies them, or manage them in your main branch and let ghp-import handle the entire `gh-pages` content. Consider using the `-o` or `--no-history` option to discard previous history and keep the repository size down.
For User/Organization Pages, use the `-b` or `--branch` flag to specify the correct branch, typically `master` or `main`. Example: `ghp-import -n -p -f _build/html -b master`.
Always include the `-n` or `--no-jekyll` flag when running `ghp-import` if your content is pre-built HTML. This tells GitHub Pages not to process your site with Jekyll, ensuring your content is served as-is.
Update to ghp-import version 1.0.0 or later to use the `from ghp_import import ghp_import` pattern for programmatic deployment, which offers clearer API and better maintainability.
To execute `ghp-import` from a Python script, you must either use the `subprocess` module (e.g., `import subprocess; subprocess.run(['ghp-import', '-n', '-p', '-f', 'docs_output'])`) or, if you intend to use the programmatic interface, import and call the library's Python API correctly (e.g., `from ghp_import import ghp_import; ghp_import.ghp_import(no_jekyll=True, push=True, doc_root='docs_output')`).
To execute `ghp-import` as a command-line tool from Python, use `subprocess.run()` (e.g., `import subprocess; subprocess.run(['ghp-import', '-n', '-p', '-f', 'docs_output'])`). For programmatic access, ensure you are importing the library directly, as described in Warning 3 (e.g., `from ghp_import import ghp_import`).
Ensure `ghp-import` is installed using `pip install ghp-import`. If already installed, verify your system's PATH includes the directory where pip installs scripts (e.g., `~/.local/bin` on Linux/macOS or `Scripts` folder in Python installation on Windows).
Upgrade `ghp-import` to the latest version using `pip install --upgrade ghp-import` to ensure you have the most compatible and current module structure.
Verify your GitHub access rights. For SSH, ensure your SSH key is correctly added to your GitHub account and your SSH agent is running. For HTTPS, update your Git credentials with a valid Personal Access Token that has repository write access.
First, try removing the local `gh-pages` branch with `git branch -D gh-pages`. If this doesn't resolve it, especially after an interrupted `gh-pages` deployment, manually clear the local cache used by deployment tools (e.g., for `gh-pages` npm package, it might be `rm -rf node_modules/.cache/gh-pages`). After cleaning, retry the `ghp-import` command.