Overview

Ghps is a minimal, zero-dependency GitHub Pages simulator written in pure Python for local development and testing. It accurately replicates GitHub Pages' static hosting behavior, including proper 404.html handling, project base path simulation, strict routing mode, and optional cache control - all while remaining lightweight, fast, and usable both as a CLI tool and as an importable Python library.

PyPI Counter
Github Stars

Branch	main	dev
CI

Code Quality

Installation

Source Code

• Download Version 0.5 or Latest Source
• pip install .

PyPI

• Check Python Packaging User Guide
• pip install ghps==0.5

Usage

Ghps can be used both as a CLI tool and as a Python library.

CLI

ghps --port=8080 --no-cache --no-threaded

Options

Option	Description	Default
-p, --port	Port to serve on	8000
-d, --directory	Directory to serve	Current directory (.)
-b, --base-path	Base path for project pages (e.g. /repo-name)	""
--no-strict	Enable .html fallback	Strict mode enabled
--no-cache	Disable HTTP caching headers	Cache enabled
--no-threaded	Disable threaded server	Threaded enabled
--auto-open	Automatically open the server URL	Disable
--directory-listing	Enable directory listing	Disable

ℹ️ You can set --port=0 to let the OS automatically select an available port

Library

from ghps import GHPageServer

server = GHPageServer(
    directory="dist",
    port=5000,
    base_path="/repo-name",
    strict=True,
    no_cache=False,
    threaded=True,
	auto_open=True,
)

server.start()

Parameters

Parameter	Type	Description	Default
directory	str	Directory to serve	"."
port	int	Port number	8000
base_path	str	Base path for project page simulation	""
strict	bool	Enforce GitHub-like routing behavior	True
no_cache	bool	Disable cache headers	False
threaded	bool	Enable threaded request handling	True
auto_open	bool	Automatically open the server URL	False
directory_listing	bool	Enable directory listing	False

ℹ️ You can set port=0 to let the OS automatically select an available port

Issues & Bug Reports

Just fill an issue and describe it. We'll check it ASAP!

• Please complete the issue template

Show Your Support

Star This Repo

Give a ⭐️ if this project helped you!

Donate to Our Project

Bitcoin

1KtNLEEeUbTEK9PdN6Ya3ZAKXaqoKUuxCy

Ethereum

0xcD4Db18B6664A9662123D4307B074aE968535388

Litecoin

Ldnz5gMcEeV8BAdsyf8FstWDC6uyYR6pgZ

Doge

DDUnKpFQbBqLpFVZ9DfuVysBdr249HxVDh

Tron

TCZxzPZLcJHr2qR3uPUB1tXB6L3FDSSAx7

Ripple

rN7ZuRG7HDGHR5nof8nu5LrsbmSB61V1qq

Binance Coin

bnb1zglwcf0ac3d0s2f6ck5kgwvcru4tlctt4p5qef

Tether

0xcD4Db18B6664A9662123D4307B074aE968535388

Dash

Xd3Yn2qZJ7VE8nbKw2fS98aLxR5M6WUU3s

Stellar

GALPOLPISRHIYHLQER2TLJRGUSZH52RYDK6C3HIU4PSMNAV65Q36EGNL

Zilliqa

zil1knmz8zj88cf0exr2ry7nav9elehxfcgqu3c5e5

Coffeete

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

0.5 - 2026-08-02

Added

• directory_listing parameter
• --directory-listing CLI argument

Changed

• 404 page headers modified
• Port validation bug fixed
• GHPageServer class start method modified
• Error messages updated
• Dependencies structure modified
• Test system modified
• README.md updated

0.4 - 2026-05-08

Added

• GHPSError class
• GHPSValidationError class
• GHPSRuntimeError class
• Port error messages

Changed

• Test system modified

0.3 - 2026-04-05

Added

• auto_open parameter
• --auto-open CLI argument
• Random port support

Changed

• Test system modified
• CLI error messages updated
• README.md updated

0.2 - 2026-03-19

Added

• Logo
• Input validation

Changed

• Test system modified
• README.md updated

0.1 - 2026-02-27

Added

• GHPageServer class
• Command line interface
• Test system