A minimal, keyboard-driven PDF viewer backed by MuPDF and configured with Lua.
gopdf provides Vim-style navigation, continuous and single-page layouts, dual-page spreads, text search and selection, outlines, links, persistent sessions and marks, configurable colors, commands, and scriptable keybindings without a permanent toolbar.
gopdf file.pdfIf no file is provided, gopdf reopens the most recently viewed document.
Useful defaults:
| Key | Action |
|---|---|
j / k |
Scroll down / up |
J / K |
Next / previous page |
/ / ? |
Search forward / backward |
n / N |
Next / previous match |
o |
Open the document outline |
gr |
Open recent files |
: |
Open the command prompt |
F1 |
View and edit keybindings |
q |
Quit |
Download a package for Linux, macOS, or Windows from the latest release.
Linux
Run the AppImage directly:
chmod +x gopdf-*-linux-x86_64.AppImage
./gopdf-*-linux-x86_64.AppImage file.pdfArch-based systems can install gopdf-git from the AUR:
yay -S gopdf-gitmacOS
Install the release matching Intel or Apple silicon, or use Homebrew:
brew install Aethar01/homebrew-gopdf/gopdfWindows
The release provides an installer with optional PDF file association and a portable zip.
gopdf /path/to/file.pdf # open a PDF
gopdf --page 20 file.pdf # start on page 20
gopdf --config custom.lua file.pdf
gopdf -v # print version
gopdf -V # enable verbose logsUse F1 to inspect or edit keybindings and :help to view available commands.
Configuration is optional and written in Lua. Start with config.example.lua, or create a small file containing only the values and bindings you want to change. Reload it with :reload-config.
The first existing configuration file for the current platform is loaded:
| Platform | Location |
|---|---|
| Any | Path passed with --config |
| Linux | ~/.config/gopdf/config.lua |
| Linux | $XDG_CONFIG_HOME/gopdf/config.lua |
| Linux | Each $XDG_CONFIG_DIRS/gopdf/config.lua |
| Linux | /etc/xdg/gopdf/config.lua |
| macOS | ~/Library/Application Support/gopdf/config.lua |
| Windows | %APPDATA%\gopdf\config.lua |
Interactive keybinding changes are stored in autogen.lua. It is loaded before config.lua, so explicit user configuration takes precedence.
Session data is stored in session.sqlite under the platform application-data directory:
| Platform | Location |
|---|---|
| Linux | $XDG_DATA_HOME/gopdf or ~/.local/share/gopdf |
| macOS | ~/Library/Application Support/gopdf |
| Windows | %APPDATA%\gopdf |
The documentation site covers:
- Configuration options and defaults
- Commands and search flags
- Lua functions and tables
- Bindable actions and default keys
The site provides documentation for the current git branch and an immutable snapshot for each tagged release. Reference content and the example configuration are generated from the same registrations used by the application:
go generate ./...Requirements:
- Go 1.25+
- MuPDF 1.25.6+
- SDL3
- pkg-config/pkgconf
- A C compiler supported by CGO
go build
go test ./...On Windows, install the dependencies from MSYS2 UCRT64:
pacman -S --needed mingw-w64-ucrt-x86_64-go mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-pkgconf mingw-w64-ucrt-x86_64-sdl3 mingw-w64-ucrt-x86_64-mupdf
go build -o gopdf.exegopdf is licensed under the AGPL.
It links against MuPDF, which is licensed under the AGPL unless you have a separate commercial license.