Photon

A browser built on Ladybird.

Run from source · Architecture · Roadmap · Contributing

Run from source

Install the platform prerequisites in contributor setup first.

git clone --recurse-submodules https://github.com/PhotonBrowser/photon.git
cd photon

On macOS, run ./photon setup --install-system-deps; on Linux, install the packages listed in contributor setup, then run ./photon setup. Follow the platform-specific build and run guidance there before launching Photon.

Setup installs or refreshes the photon command and ph alias in Cargo's bin directory. Make sure ~/.cargo/bin is on your PATH to use photon without the ./ prefix.

To work on the GPUI shell on Linux without setting up Ladybird Engine, clone without submodules and use the UI-only path:

git clone https://github.com/PhotonBrowser/photon.git
cd photon
./photon setup --ui-only
photon run --ui

This opens the New Tab page and Photon-owned settings pages; web pages require the full Engine setup.

Develop Photon

Start with contributor setup, then use the build guide and architecture guide. See contribution guidance for pull requests and the roadmap for planned work.

flowchart LR
    User[You] --> App[photon-app]
    App --> Shell[photon-shell<br/>windows, tabs, and UI]
    Shell --> Core[photon-core<br/>browser rules and state]
    Shell --> Storage[photon-storage<br/>profile files]
    Shell --> Embedder[Photon Engine API]
    Embedder --> Engine[Ladybird Engine<br/>web pages]
    Shell --> Platform[Platform adapters<br/>macOS · Linux · Windows]
    Shell --> PerfUI[photon-performance-ui<br/>GPUI charts and overlays]
    PerfUI --> Perf[photon-performance<br/>sampling and diagnostics]
    FFI[photon-ffi<br/>C API] --> Core
    CLI[photon-cli<br/>setup and developer commands]

The shell connects the browser interface to framework-independent browser rules, profile storage, and the Ladybird Engine. See the architecture guide for component boundaries and common change locations.

Star History