GitHub Pages Import

2.1.0 · active · verified Sun Apr 05

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.

Warnings

breaking ghp-import will DESTROY your `gh-pages` branch. It assumes that the `gh-pages` branch is 100% derivative of your source files. Any manual edits made directly on the `gh-pages` branch will be lost upon execution.
Fix: 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.
gotcha By default, ghp-import pushes to the `gh-pages` branch. For GitHub User or Organization Pages (e.g., `username.github.io` or `orgname.github.io`), the content is served from the `master` (or `main`) branch. Pushing to `gh-pages` in this scenario will not publish your site.
Fix: 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`.
gotcha If your static site generator already produces complete HTML, GitHub Pages' default Jekyll processing can interfere. This might lead to unexpected rendering issues or files not being served correctly.
Fix: 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.
deprecated Before version 1.0.0, programmatic usage of ghp-import was less straightforward and sometimes involved vendoring or modifying the script. Directly importing `ghp_import` as a Python function with keyword arguments was fully supported from version 1.0.0.
Fix: 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.

Install

pip install ghp-import Install with pip

Imports

ghp_import
```
from ghp_import import ghp_import
```
This is for programmatic use; the library is primarily a command-line tool.

Quickstart

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.

# Using as a command-line tool (recommended for typical use cases)
# Assuming your built documentation is in a 'docs_output' directory
# This command will create/update the gh-pages branch, add a .nojekyll file, and push.
ghp-import -n -p -f docs_output

# Using programmatically (if you need to integrate into a Python script)
from ghp_import import ghp_import

# Example: deploy 'build' directory, push to origin, include .nojekyll
ghp_import('build', push=True, nojekyll=True, mesg='Update GitHub Pages via script')

view raw JSON →