Reference

This page is generated from the same registries used by the application.

Configuration options

Assign options with gopdf.options.<name> = <value> in Lua or :set <name>=<value> at runtime. Colors use { r, g, b } in Lua and r,g,b or #RRGGBB with :set.

Option	Type	Default	Description
alt_background	color	{20, 20, 20}	Viewer background in alternate-color mode.
alt_colors	boolean	false	Start with alternate colors enabled.
alt_foreground	color	{255, 255, 255}	UI foreground in alternate-color mode.
alt_page_background	color	{17, 17, 17}	Page background in alternate-color mode.
alt_status_bar_color	color	{20, 20, 20}	Status bar background in alternate-color mode.
anchor_position	string	"center"	Viewport anchor: center, top, or bottom.
anti_aliasing	integer	8	MuPDF antialiasing level from 0 through 8.
background	color	{220, 220, 220}	Viewer background color.
completion_max_items	integer	10	Maximum command-completion rows.
copy_on_select	boolean	true	Copy selected text to the clipboard when the mouse selection is released.
dual_page	boolean	false	Start in dual-page mode.
first_page_offset	boolean	true	Treat the first page as a standalone cover in dual-page mode.
fit_mode	string	"page"	Initial fit mode: page, width, or manual.
foreground	color	{20, 20, 20}	UI foreground color.
highlight_background	color	{255, 224, 102}	Selection and search highlight background.
highlight_foreground	color	{0, 0, 0}	Selection and search highlight border and text.
invert_scroll	boolean	false	Invert horizontal and vertical discrete mouse-wheel scrolling.
invert_smooth_scroll	boolean	false	Invert horizontal and vertical smooth wheel or trackpad scrolling.
max_zoom	number	8	Maximum manual zoom scale.
min_zoom	number	0.5	Minimum manual zoom scale.
mouse_text_select	boolean	true	Enable text selection with the left mouse button.
outline_height_percent	integer	80	Outline overlay height as a percentage of the window.
outline_initial_depth	integer	1	Outline levels expanded when the outline opens.
outline_width_percent	integer	70	Outline overlay width as a percentage of the window.
page_background	color	{255, 255, 255}	Normal page background color.
page_cache_size	integer	16	Maximum rendered pages retained in the cache.
page_gap	integer	0	Vertical gap between pages; aliases page_gap_vertical.
page_gap_horizontal	integer	0	Horizontal gap between pages in a spread.
page_gap_vertical	integer	0	Vertical gap between page rows.
pinch_sensitivity	number	1	Trackpad pinch zoom sensitivity; 1 preserves the gesture scale.
recent_files_max	integer	20	Maximum recent files retained and displayed.
render_mode	string	"continuous"	Initial render mode: continuous or single.
render_oversample	number	1	Render scale multiplier; values above 1 supersample.
scroll_off	integer	0	Minimum number of rows kept visible above and below the selected item in UI menus, like Vim's scrolloff.
scroll_step	integer	64	Keyboard and mouse scroll distance in pixels.
sequence_timeout_ms	integer	700	Maximum delay between keys in a binding sequence.
session_database	boolean	true	Persist per-document view state, marks, and recent files.
smooth_scroll	boolean	true	Animate mouse-wheel and trackpad scrolling, including scrollable UI lists.
smooth_scroll_dampening	number	0.8	Smooth-scroll catch-up factor per 16ms frame; higher values are more responsive and less damped; clamped to 0.01 through 1.
spread_gap	integer	0	Horizontal spread gap; aliases page_gap_horizontal.
status_bar_color	color	{220, 220, 220}	Normal status bar background color.
status_bar_left	string	"{message}"	Left status bar template.
status_bar_padding	integer	8	Horizontal status bar padding in pixels.
status_bar_right	string	"{page}/{total} {mode} fit={fit} rot={rot} {zoom}"	Right status bar template.
status_bar_visible	boolean	true	Show the status bar at startup.
ui_font	string	""	Installed UI font family; empty uses the built-in font.
ui_font_path	string	""	Explicit UI font file path; overrides ui_font, ui_font_style, and ui_font_weight.
ui_font_size	integer	14	UI font size in pixels.
ui_font_style	string	"normal"	UI font style: normal, italic, or oblique.
ui_font_weight	font-weight	400	UI font weight as CSS number 100-900 or alias such as normal, medium, semibold, bold, or black.

Commands

Command	Description
:colors normal|alt	Set color mode
:fit width|page|manual	Set fit mode
:help	Show this command help window
:keybinds	Toggle the keybinds menu
:lua <code>	Execute Lua code inline
:mode continuous|single	Set render mode
:open <filename>	Open another PDF relative to the current document
:open_file_picker	Open the PDF file picker
:page PAGE, :p PAGE, :N	Jump to a page number or label
:quit, :q	Exit
:reload-config	Reload the config file
:recent	Open the recent-files menu
:search [-r] [-i] [-w] [-p] <text>	Search document text
:set [option[?]|option!|option=value]	Inspect or change options

Search flags: -r regular expression, -i ignore case, -w whole word, and -p current page only. Flags can be combined.

Lua functions

Function	Description
gopdf.bind(key, action)	Bind a key sequence to an action or Lua callback.
gopdf.bind_mouse(event, action)	Bind a mouse event to an action or Lua callback.
gopdf.cache.clear()	Clear rendered-page caches.
gopdf.cache.entries()	Return the number of cached rendered pages.
gopdf.cache.limit([limit])	Return the rendered-page cache limit, or set and return it when supplied.
gopdf.cache.pending()	Return the number of pending renders.
gopdf.clear_pending_keys()	Clear the pending sequence, mark, and numeric count.
gopdf.clipboard.get_text()	Return the current UTF-8 clipboard text.
gopdf.clipboard.set_text(text)	Replace the clipboard with UTF-8 text.
gopdf.command(command)	Execute a viewer command.
gopdf.current_count()	Return the pending numeric action count.
gopdf.fit_mode([mode])	Return the current fit mode, or set and return it when supplied.
gopdf.formats.extensions()	Return the lower-case extensions, without a leading dot, that this build can open.
gopdf.formats.supports(path)	Report whether a path's extension names an openable format. Opening also sniffs content, so a file without a known extension may still open.
gopdf.fullscreen([enabled])	Return fullscreen state, or set and return it when supplied.
gopdf.goto_document_point(spec)	Move to a 1-based page and document coordinate.
gopdf.log(level, message)	Write a plugin diagnostic without changing the user-facing message.
gopdf.message([text])	Return the current message, or set and return it when text is supplied.
gopdf.mode()	Return the current input mode.
gopdf.open(path)	Open another document.
gopdf.open_external(uri_or_path)	Open a URI or path with the operating system's default application.
gopdf.page([page])	Return the current 1-based physical page number, or go to and return it when supplied.
gopdf.page_count()	Return the document page count.
gopdf.pending_keys()	Return pending key-sequence tokens.
gopdf.pick_directory(callback)	Open the native directory picker and invoke callback with a structured result.
gopdf.pick_file(callback)	Open the native document picker and invoke callback with a structured result. The picker is filtered to the formats this build can open.
gopdf.plugin.register(id[, spec])	Register and return a lazily loaded Lua plugin module.
gopdf.recent_files([limit])	Return recent document paths.
gopdf.render_mode([mode])	Return the current render mode, or set and return it when supplied.
gopdf.rotation([degrees])	Return clockwise rotation, or set and return it when supplied.
gopdf.schedule(callback)	Schedule a callback on the main Lua thread after the current dispatch.
gopdf.search(query[, backward])	Search using the same flags as :search.
gopdf.search_match_count()	Return the number of discovered search matches.
gopdf.search_match_index()	Return the current 1-based match index or nil.
gopdf.search_query()	Return the active search query.
gopdf.status_bar_visible([visible])	Return status bar visibility, or set and return it when supplied.
gopdf.ui.create(spec)	Create a list view using the same UI model as built-in viewer screens.
gopdf.unbind(key)	Remove a key binding.
gopdf.unbind_mouse(event)	Remove a mouse binding.
gopdf.zoom([scale])	Return the current render scale, or set and return it when supplied.

UI views

Create views with local view = gopdf.ui.create(spec), then call view:show(). The specification supports id, title, rows, selected, scroll, query, searchable, on_select, and on_close. A row may be a string or a table with text, value, id, secondary, depth, and disabled.

View methods are show(), close(), visible(), set_rows(rows), set_selected(index), set_scroll(scroll), set_query(query), selected(), scroll(), and query(). Selection indices are 1-based, with 0 meaning no selection. on_select receives (index, value, text, id), preserving the original row index and ID when the list is filtered. on_close runs for user, programmatic, replacement, and document-close paths.

Portable API

The gopdf tables below are available to configuration and plugin Lua code.

Module	Returns / fields	Description
gopdf.platform	table	Also available from require("gopdf.platform"). Fields: os (linux, macos, or windows), arch, home_dir, config_dir, data_dir, cache_dir, and temp_dir. Directory fields are absolute when the platform supplies a location and may be empty when it does not.
gopdf.path	table	Also available from require("gopdf.path"). Fields: separator, list_separator; functions: join(...), clean(path), basename(path), dirname(path), extension(path), is_absolute(path), absolute(path), relative(base, target), and expand_home(path). Operations use native platform path rules; expand_home expands only ~, ~/..., and ~\....
gopdf.json	table	Also available from require("gopdf.json"). encode(value) returns compact JSON and decode(text) returns a Lua value. null is the stable module-local JSON null sentinel. Arrays require contiguous positive integer keys; objects require string keys. Cycles, sparse or mixed tables, non-finite numbers, unsupported Lua values, and trailing input are errors. Decoded empty arrays and objects retain their shape when re-encoded.

Host services

Function	Returns / fields	Description
gopdf.schedule(callback)	handle	Queue callback() on the main Lua thread after the current dispatch. It is asynchronous and can be cancelled through the returned handle.
gopdf.log(level, message)	none	Write a diagnostic without changing the viewer message. level must be debug, info, warn, or error; output is tagged with the loading plugin ID, or config outside plugin loading.
gopdf.open_external(uri_or_path)	none	Ask the operating system to open a URI or path with its default application. Raises an error when the viewer host is unavailable or rejects the request.
gopdf.formats.extensions()	string[]	Return the lower-case extensions, without a leading dot, that the linked document engine can open. The set is read from the engine, so it matches what this build supports.
gopdf.formats.supports(path)	boolean	Report whether a path's extension names an openable format. Matching ignores case. Opening also recognises documents by content, so a file with a missing or misleading extension may still open.
gopdf.clipboard.get_text()	string	Synchronously return the current UTF-8 clipboard text. Raises an error when clipboard access is unavailable.
gopdf.clipboard.set_text(text)	none	Synchronously replace the clipboard with UTF-8 text. Raises an error when clipboard access is unavailable or fails.
gopdf.pick_file(callback)	none	Open the native document picker, filtered to the formats this build can open, then call callback(result). The call returns after the picker and callback complete.
gopdf.pick_directory(callback)	none	Open the native directory picker, then call callback(result). The call returns after the picker and callback complete.

Document inspection

These read the open document. The gopdf.document fields path, name, extension, exists, size_bytes, and page_count remain available and are refreshed when the document changes. The functions below raise an error when no document is open. Rectangles are x0, y0, x1, y1 in unrotated PDF points.

Function	Returns / fields	Description
gopdf.document.metadata()	table	Return document metadata: format, encryption, title, author, subject, keywords, creator, producer, creation_date, and modification_date. Absent fields are empty strings.
gopdf.document.outline()	table[]	Return the outline as a tree. Each entry has title, uri, external, page, children, and optional x and y destination coordinates. page is 1-based, or 0 when the entry has no page destination.
gopdf.document.page_info(page)	table	Return page, label, width, height, and bounds for a 1-based page. Sizes are unrotated PDF points; an out-of-range page raises an error.
gopdf.document.selection()	table	Return the current selection: active, page, text, and quads as bounding rectangles. page is 0 when nothing is or was selected.
plugin.document:page_text(page, callback)	handle	Extract a page's text asynchronously. The result adds page and text.
plugin.document:page_links(page, callback)	handle	Read a page's links asynchronously. The result adds page and links; each link has bounds, uri, external, page, and optional x and y.

Plugins

Plugins are discovered without being executed. Enable one explicitly with local plugin = require("plugin-id"); only the required plugin and its declared dependencies execute. The entrypoint must call gopdf.plugin.register("plugin-id"[, spec]); require returns the registered module.

A plugin manifest is gopdf-plugin.json with id, version, module, and dependencies; only id is required, and unrecognised fields are ignored. module selects lua/<module>.lua or lua/<module>/init.lua. Plugin modules contain id, version, actions, fs, timer, storage, http, and document, plus register_action, register_command, on, off, and job. Registered actions use plugin-id.action; commands use :plugin-id-command; options use plugin-id.option.

Function	Returns / fields	Description
plugin.fs:read_dir(path[, options], callback)	handle	Read one directory asynchronously. options.follow_symlinks defaults to false. Without following, a symlink supplied as path is rejected; entries themselves are reported as symlinks.
plugin.fs:stat(path[, options], callback)	handle	Stat a path asynchronously. options.follow_symlinks defaults to false.
plugin.timer:after(ms, callback)	handle	Call callback() once after ms milliseconds. ms may be zero.
plugin.timer:every(ms, callback)	handle	Call callback() repeatedly, waiting ms milliseconds between dispatches. ms must be greater than zero.
plugin.storage:get(key)	value or nil	Synchronously return the value stored for this plugin ID, or nil when absent or when no session database is available.
plugin.storage:set(key, value)	none	Synchronously persist a plugin-scoped value. Supports nil, booleans, finite numbers, strings, contiguous arrays, and string-keyed objects; tables cannot be cyclic or mix array and object keys. Raises an error when no session database is available; the value is not silently discarded.
plugin.storage:delete(key)	none	Synchronously delete a plugin-scoped value.
plugin.storage:keys()	string[]	Synchronously return this plugin's keys in lexical order.
plugin.http:request(spec, callback)	handle	Make an asynchronous HTTP request. spec has required url (http or https) and optional method (default GET), string-to-string headers, body, and positive timeout_ms.
plugin:job(spec, callback)	handle	Start a subprocess without invoking a shell. spec.command is required; optional fields are string-array args, cwd, positive timeout_ms, string-to-string env additions, and stdin.

Handles and results

Every schedule, filesystem, timer, HTTP, document-extraction, and job call returns a handle with numeric id, cancel(), and active(). active() becomes false before a one-shot completion callback runs. Repeating timers remain active between callbacks until cancelled. cancel() is idempotent, removes the operation, and does not invoke its callback, so delivered result tables always have cancelled=false. Callbacks run serially on the main Lua thread, never on worker goroutines.

Result	Returns / fields	Description
picker result	success, path, cancelled, error	Cancellation is a normal result: cancelled=true, success=false, empty path, and empty error.
fs.stat result	success, error, cancelled, timed_out; on success: name, path, type, size_bytes, modified_unix	type is file, directory, symlink, or other. modified_unix is whole seconds since the Unix epoch.
fs.read_dir result	success, error, cancelled, timed_out, entries	On success, entries is an array of the same file-information fields returned by stat.
http result	success, status, headers, body, error, timed_out, cancelled	On transport failure, status is 0 and body and headers are empty. Response header values are arrays of strings. HTTP error status codes are completed responses and do not by themselves set success=false.
job result	id, success, code, stdout, stderr, error, timed_out, cancelled	success requires exit code 0, no launch/wait error, and no timeout. code is -1 when no process exit code is available.

Limits

Resource	Returns / fields	Description
Storage value	65,536 bytes	Limit applies to the encoded JSON value for each key.
HTTP response body	8 MiB	A larger response fails the operation; request bodies have no API-specific size limit.
HTTP redirects	10	Following a redirect after the tenth redirect fails the operation.
Job stdout	4 MiB	Captured independently; additional output is discarded.
Job stderr	4 MiB	Captured independently; additional output is discarded.

Lifecycle

Each plugin has an isolated local-module cache and search root. It may require another discovered plugin by ID only when that ID is declared in dependencies. Dependencies load first, and events are delivered in activation order, so dependencies receive an event before their dependents. Registration of actions, commands, and event subscriptions is allowed only while the plugin entrypoint is loading; off(id), storage calls, timers, filesystem and HTTP operations, and jobs remain available afterward.

A successful :reload-config replaces the Lua state and cancels all handles and jobs from the old generation without invoking their callbacks. If reload fails, the previous state and its operations remain active. A failed plugin load rolls back that plugin and cancels work it started. Viewer shutdown emits shutdown before runtime close; close then cancels remaining operations and jobs. Storage is keyed by plugin ID in the session database and survives reloads and application restarts.

Supported events are app_ready, document_open_pre, document_opened, document_close_pre, document_closed, document_reloaded, config_reloaded, mouse_button_pre, mouse_button, selection_changed, page_changed, zoom_changed, option_changed, and shutdown. page_changed carries page, label, previous_page, and page_count; zoom_changed carries scale, previous_scale, and percent. Both are emitted once per frame with the settled value, so a continuous gesture reports where it came to rest. Event callbacks run in subscription order within each plugin; returning true marks an event consumed where the host supports consumption but does not stop later callbacks.

Plugin search paths are the platform data/config plugin directories and are rescanned by :reload-config. Disable plugin discovery with --no-plugins, or start from built-in defaults with --no-config, which also skips the generated settings file.

Single instance

Instances are per document. Each window listens on a socket named after the document it is showing, and the address follows the document when the window opens another one. --unique hands the request to the window already showing that document and exits; with no such window, this process opens it. --goto PAGE opens at a page and --goto PAGE:X:Y at a point on it, overriding any remembered session position, whether the work is done here or by an existing window. --command TEXT runs a viewer command there, as typed after :, including any command registered by a plugin. An unrecognised command exits non-zero. X and Y are points measured from the page's top-left corner, which is also SyncTeX's convention. Sockets live under $XDG_RUNTIME_DIR/gopdf on Linux, the per-user temporary directory on macOS, and %LOCALAPPDATA%\gopdf on Windows. They are mode 0600 and named by a hash of the document path, which keeps them within the platform socket length limit. A socket left by a crashed process is reclaimed on the next start.

Bindable actions

Every action is available as gopdf.<action>, can be passed to gopdf.bind, and can be called from a runtime Lua callback.

Action	Default keys	Countable
next_page	J, Space, <PgDn>	true
prev_page	K, <PgUp>	true
scroll_down	j, <Down>	true
scroll_up	k, <Up>	true
scroll_left	h, <Left>	true
scroll_right	l, <Right>	true
next_spread		true
prev_spread		true
first_page	gg	false
last_page	G	false
command_mode	:	false
search_prompt	/	false
search_prompt_backward	?	false
search_next	n	true
search_prev	N	true
toggle_dual_page	d	false
toggle_render_mode	m	false
toggle_alt_colors	<C-r>	false
toggle_first_page_offset	co	false
toggle_status_bar	<C-n>	false
toggle_fullscreen	f	false
outline	o	false
confirm	<CR>	false
zoom_in	+, =	true
zoom_out	-	true
reset_zoom	0	false
fit_width	a	false
fit_page	s	false
reload_config	<C-S-r>	false
rotate_cw	r	false
rotate_ccw	R	false
goto_page_prompt	<C-g>	false
clear_search		false
show_completion	<Tab>	false
next_completion		false
prev_completion	<S-Tab>	false
copy	<C-c>	false
cut	<C-x>	false
paste	<C-v>	false
close	<Esc>	false
jump_forward	<C-i>	false
jump_backward	<C-o>	false
open_file_picker	<C-S-o>	false
show_recent_files	gr	false
keybinds	<F1>	false
pan		false
quit	q	false

Lua tables

• gopdf.document: path, name, extension, exists, size_bytes, and page_count.
• gopdf.status_bar: left, right, and visible.
• gopdf.options: all entries from the configuration-options table.
• gopdf.cache, gopdf.ui, and gopdf.plugin: functions are listed above.