{"library":"ghp-import","title":"GitHub Pages Import","description":"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.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/c-w/ghp-import","tags":["documentation","github-pages","deployment","static-sites","automation"],"install":[{"cmd":"pip install ghp-import","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for date/time utilities, possibly for commit timestamping.","package":"python-dateutil","optional":false}],"imports":[{"note":"This is for programmatic use; the library is primarily a command-line tool.","symbol":"ghp_import","correct":"from ghp_import import ghp_import"}],"quickstart":{"code":"# Using as a command-line tool (recommended for typical use cases)\n# Assuming your built documentation is in a 'docs_output' directory\n# This command will create/update the gh-pages branch, add a .nojekyll file, and push.\nghp-import -n -p -f docs_output\n\n# Using programmatically (if you need to integrate into a Python script)\nfrom ghp_import import ghp_import\n\n# Example: deploy 'build' directory, push to origin, include .nojekyll\nghp_import('build', push=True, nojekyll=True, mesg='Update GitHub Pages via script')\n","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"< 1.0.0"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}