{"id":1101,"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":"python","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"},{"fix":"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')`).","message":"Attempting to run `ghp-import` directly as a shell command within a Python script (e.g., `ghp-import -n -p -f docs_output`) will result in a `SyntaxError`. Python does not execute shell commands directly; they must be run via the `subprocess` module or by importing and calling the library's Python API.","severity":"breaking","affected_versions":"All versions"},{"fix":"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`).","message":"Attempting to run `ghp-import` shell commands directly within a Python script will result in a `SyntaxError`. ghp-import is designed as a command-line tool. To execute it from a Python script, you must use the `subprocess` module (e.g., `subprocess.run(['ghp-import', '-n', '-p', '-f', 'docs_output'])`) or, if supported, import it programmatically (e.g., `from ghp_import import ghp_import`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2.1.0':54 '2022':71 'activ':61 'autom':24,80 'branch':40 'built':29 'cadenc':63 'commit':46 'content':19 'copi':28 'current':51 'deploy':16,76 'design':12 'document':30,72 'file':34 'gh':38 'gh-page':37 'ghp':5 'ghp-import':4 'github':1,21,43,74 'github-pag':73 'import':3,6 'infrequ':59 'last':66 'lightweight':9 'major':67 'may':70 'packag':11 'page':2,22,39,75 'process':26 'push':48 'python':10 'releas':62,68 'repositori':44 'simplifi':14 'site':79 'static':18,33,78 'static-sit':77 'version':52","created_at":"2026-04-05T13:05:45.068614+00:00","updated_at":"2026-04-16T15:16:11.273942+00:00","problems":[{"fix":"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).","cause":"The `ghp-import` executable is not found in your system's PATH, typically because the package was not installed or its installation directory is not properly configured in your environment variables.","error":"ghp-import: command not found"},{"fix":"Upgrade `ghp-import` to the latest version using `pip install --upgrade ghp-import` to ensure you have the most compatible and current module structure.","cause":"This error typically occurs with older versions of `ghp-import` or when there's a conflict in the Python environment, where the entry point `main` cannot be imported from the `ghp_import` module.","error":"ImportError: cannot import name main"},{"fix":"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.","cause":"This error indicates that your Git client lacks the necessary authentication or authorization to push changes to the GitHub repository. This is usually due to incorrect SSH keys, expired Personal Access Tokens (PATs), or insufficient repository permissions.","error":"ERROR: Permission to <username>/<repository>.git denied to <user>. fatal: Could not read from remote repository."},{"fix":"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.","cause":"This Git error occurs when `ghp-import` attempts to create or manage the `gh-pages` branch, but a local reference to that branch already exists in your Git repository, possibly from a previous interrupted deployment or a corrupted local cache.","error":"fatal: A branch named 'gh-pages' already exists"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.1.0","cli_name":"ghp-import","cli_version":"2.1.0","type":"library","homepage":null,"github":"https://github.com/c-w/ghp-import","docs":null,"changelog":null,"pypi":"https://pypi.org/project/ghp-import/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}