ZATHURARC(5)

💖 zathurarc(5) — the zathura config file, bestie edition 💖

🌸 NAME 🌸

zathurarc — zathura configuration file. That's it, that's the name section, but it's kind of a big deal.

✨ SYNOPSIS ✨

/etc/zathurarc, $XDG_CONFIG_HOME/zathura/zathurarc

🦋 DESCRIPTION 🦋

Okay so the zathurarc file is a simple plain text file that you can fill with all kinds of commands to change how zathura behaves and how it looks. We're gonna walk through all of that in the subsections below, bestie.

Each line (besides empty lines and comments, which start with a prepended #) is evaluated on its own. So no cap: it is not possible to write multiple commands in one single line. One line, one command, periodt.

💅 COMMANDS 💅

🎀 set — Changing options 🎀

In addition to the built-in :set command, zathura offers more options to be changed and makes those changes permanent. To overwrite an option, you just have to add a line structured like the following:

set <option> <new value>

The option field has to be replaced with the name of the option that should be changed, and the new value field has to be replaced with the new value the option should get. The type of the value can be one of the following:

• INT — An integer number
• FLOAT — A floating point number
• STRING — A character string
• BOOL — A boolean value ("true" for true, "false" for false)

Also, bestie, we advice you to check the options so you get a more detailed view of the options that can be changed and which values they should be set to.

The following example should give some deeper insight into how the set command can be used:

set option1 5
set option2 2.0
set option3 hello
set option4 hello\ world
set option5 "hello world"

Especially for options with strings as values, note that escaping of special characters and white spaces is necessary. In the above example, option4 and option5 are both set to hello world, but set option6 hello world would set option6 only to hello.

For colors, zathura supports HTML color codes and CSS3-style rgb(r,g,b) and rgba(r,g,b,a) values. If you want to use color codes for some options, make sure to quote them accordingly or to escape the hash symbol.

set default-fg "#CCBBCC"
set default-fg \#CCBBCC

For rgba, note that it parses the color components as integers between 0 and 255 and the alpha component as float between 0 and 1.

🧚 include — Including another config file 🧚

This command allows one to include other configuration files. If a relative path is given, the path will be resolved relative to the configuration file that is currently processed.

include another-config

🗺️ map — Mapping a shortcut 🗺️

It is possible to map or remap new key bindings to shortcut functions, which allows a high level of customization. The :map command can also be used in the zathurarc file to make those changes permanent:

map [mode] <binding> <shortcut function> <argument>

🧚 Mode 🧚

The map command expects several arguments where only the binding as well as the shortcut-function argument is required. Since zathura uses several modes, it is possible to map bindings only for a specific mode by passing the mode argument, which can take one of the following values:

• normal (default)
• fullscreen
• presentation
• index

🚨 The brackets around the value are mandatory.

🔑 Single key binding 🔑

The (possible) second argument defines the used key binding that should be mapped to the shortcut function and is structured like the following. On the one hand it is possible to just assign single letters, numbers or signs to it:

map a shortcut_function optional_argument
map b shortcut_function optional_argument
map c shortcut_function optional_argument
map 1 shortcut_function optional_argument
map 2 shortcut_function optional_argument
map 3 shortcut_function optional_argument
map ! shortcut_function optional_argument
map ? shortcut_function optional_argument

🎛️ Using modifiers 🎛️

It is also possible to use modifiers like the Control or Alt button on the keyboard. It is possible to use the following modifiers:

• A — Alt
• C — Control
• S — Shift

If any of the modifiers should be used for a binding, it is required to define the binding with the following structure:

map <A-a> shortcut_function
map <C-a> shortcut_function

⌨️ Special keys ⌨️

zathura allows it also to assign keys like the space bar or the tab button, which also have to be written in between angle brackets. The following special keys are currently available:

• BackSpace — Back space
• CapsLock — Caps lock
• NumLock — Num Lock
• ScrollLock — Scroll Lock
• Esc — Escape
• Down — Arrow down
• Up — Arrow up
• Left — Arrow left
• Right — Arrow right
• F1 — F1
• F2 — F2
• F3 — F3
• F4 — F4
• F5 — F5
• F6 — F6
• F7 — F7
• F8 — F8
• F9 — F9
• F10 — F10
• F11 — F11
• F12 — F12
• PageDown — Page Down
• PageUp — Page Up
• Return — Return
• Space — Space
• Super — Windows key
• Tab — Tab
• Print — Print key
• KPUp — Numpad Up (where the number 8 is)
• KPDown — Numpad Down (where the number 2 is)
• KPLeft — Numpad Left (where the number 4 is)
• KPRight — Numpad Right (where the number 6 is)
• KPBegin — Numpad Center button (where the number 5 is)
• KPPrior — Numpad PageUp (where the number 9 is)
• KPPageUp — Numpad PageUp (where the number 9 is)
• KPNext — Numpad PageDown (where the number 3 is)
• KPPageDown — Numpad PageDown (where the number 3 is)
• KPHome — Numpad Home (where the number 7 is)
• KPEnd — Numpad End (where the number 1 is)
• KPInsert — Numpad Insert (where the number 0 is)
• KPDelete — Numpad Delete (where the numpad period is)
• KPMultiply — Numpad Asterisk
• KPAdd — Numpad Plus sign
• KPSubtract — Numpad Minus sign
• KPDivide — Numpad Slash sign

Of course it is possible to combine those special keys with a modifier. The usage of those keys should be explained by the following examples:

map <Space> shortcut_function
map <C-Space> shortcut_function

🖱️ Mouse buttons 🖱️

It is also possible to map mouse buttons to shortcuts by using the following special keys:

• Button1 — Mouse button 1 (left)
• Button2 — Mouse button 2 (middle)
• Button3 — Mouse button 3 (right)
• Button4 — Mouse button 4
• Button5 — Mouse button 5

They can also be combined with modifiers:

map <Button1> shortcut_function
map <C-Button1> shortcut_function

📥 Buffer commands 📥

If a mapping does not match one of the previous definition but is still a valid mapping, it will be mapped as a buffer command:

map abc quit
map test quit

⚡ Shortcut functions ⚡

The following shortcut functions can be mapped:

• abort — Switch back to normal mode.
• adjust_window — Adjust page width. Possible arguments are best-fit and width.
• change_mode — Change current mode. Pass the desired mode as argument.
• copy_filepath — Copy the full path of the currently opened document to the clipboard
• copy_link — Copy a link target to the clipboard.
• cycle_first_column — In multiple page layout, cycle the column in which the first page is displayed.
• display_link: — Display link target.
• exec: — Execute an external command. $FILE expands to the current document path, $PAGE to the current page number, and $DBUS to the bus name of the D-Bus interface.
• file_chooser: — Open a File Chooser Dialog. Uses the native file chooser on Windows and MacOS, desktop portals when available and otherwise GtkFileChooser.
• focus_inputbar — Focus inputbar.
• follow — Follow a link.
• goto — Go to a certain page.
• jumplist — Move forwards/backwards in the jumplist. Pass forward as argument to move to the next entry and backward to move to the previous one.
• navigate — Navigate to the next/previous page.
• navigate_index — Navigate through the index.
• print — Show the print dialog.
• page_mode — Set the page sizing mode. Default is equal_none, which doesn't resize individual pages. equal_width and equal_height resizes each page to have the same width and height respectively.
• quit — Quit zathura.
• recolor — Recolor pages.
• reload — Reload the document.
• rotate — Rotate the document. Pass rotate-ccw as argument for counterclockwise rotation and rotate-cw for clockwise rotation.
• rotate_page — Rotate the page. Pass rotate-ccw as argument for counterclockwise rotation and rotate-cw for clockwise rotation.
• scroll — Scroll.
• search — Search next/previous item. Pass forward as argument to search for the next hit and backward to search for the previous hit.
• set — Set an option.
• snap_to_page — Snaps to the current page. Equivalent to goto <current_page>
• toggle_fullscreen — Toggle fullscreen.
• toggle_index — Show or hide index.
• toggle_inputbar — Show or hide inputbar.
• toggle_page_mode — Toggle between one and multiple pages per row.
• toggle_single_page_mode

Toggle between a page grid and a single page. That's the whole vibe check. ✨

• toggle_statusbar — show or hide the statusbar. 🎀
• zoom — zoom in or out, bestie. 🔍
• zoom_page — zoom in or out, but just of the current page (yes, they're different, iykyk).
• mark_add — set a quickmark. 📌
• mark_evaluate — jump to a quickmark. like, go there. 👑
• feedkeys — simulates key presses. heads up though: every key gets interpreted exactly as if you pressed it on the actual keyboard. so to input uppercase letters, follow the same convention as for key bindings — meaning for X, you write <S-X>. 💅

🫶 Pass arguments 🫶

Some shortcut functions need or optionally take arguments that change how they behave. You pass them as the last argument, like this:

map <C-i> zoom in
map <C-o> zoom out

The possible arguments are, alphabetically because we're organized like that:

• best-fit
• bottom
• backward
• collapse
• collapse-recursive
• collapse-all
• default
• down
• expand
• expand-recursive
• expand-all
• forward
• full-down
• full-up
• half-down
• half-up
• smooth-down
• smooth-up
• in
• left
• next
• out
• page-bottom
• page-top
• previous
• right
• rotate-ccw
• rotate-cw
• select
• specific
• toggle
• top
• up
• width
• equal_none
• equal_width
• equal_height

---

✂️ unmap - Removing a shortcut ✂️

So mapping and remapping custom key bindings is a whole thing, but plot twist: you can also remove ones that already exist, with the :unmap command. It goes like this (and the parameters are explained in the map section of this document, in case you're nosy):

unmap [mode] <binding>

---

✨ OPTIONS ✨

Okay so this whole section is about the settings that control how zathura behaves. Every single one listed here can be changed with set. Let's get into it 💖

• n-completion-items — the max number of completion entries that get displayed.
  • Value type: Integer
  • Default value: 15
• completion-bg — the background color for command line completion entries.
  • Value type: String
  • Default value: #232323
• completion-fg — the foreground color for command line completion entries.
  • Value type: String
  • Default value: #DDDDDD
• completion-group-bg — the background color used for command line completion group elements.
  • Value type: String
  • Default value: #000000
• completion-group-fg — the foreground color used for command line completion group elements.
  • Value type: String
  • Default value: #DEDEDE
• completion-highlight-bg — the background color used for the current command line completion element (the one you're hovering on, main character energy).
  • Value type: String
  • Default value: #9FBC00
• completion-highlight-fg — the foreground color used for the current command line completion element.
  • Value type: String
  • Default value: #232323
• default-bg — the default background color.
  • Value type: String
  • Default value: #000000
• default-fg — the default foreground color.
  • Value type: String
  • Default value: #DDDDDD
• exec-command — defines a command that should be prepended to any command run with exec.
  • Value type: String
  • Default value: (empty)
• font — the font that will be used. 💅
  • Value type: String
  • Default value: monospace normal 9
• guioptions — shows or hides GUI elements. If it contains c, the command line is displayed. If it contains s, the statusbar is displayed. If it contains h, the horizontal scrollbar is displayed. If it contains v, the vertical scrollbar is displayed.
  • Value type: String
  • Default value: s
• inputbar-bg — the background color for the inputbar.
  • Value type: String
  • Default value: #131313
• inputbar-fg — the foreground color for the inputbar.
  • Value type: String
  • Default value: #9FBC00
• notification-bg — the background color for a notification.
  • Value type: String
  • Default value: #FFFFFF
• notification-fg — the foreground color for a notification.
  • Value type: String
  • Default value: #000000
• notification-error-bg — the background color for an error notification 🚨
  • Value type: String
  • Default value: #FF1212
• notification-error-fg — the foreground color for an error notification.
  • Value type: String
  • Default value: #FFFFFF
• notification-warning-bg — the background color for a warning notification ⚠️
  • Value type: String
  • Default value: #FFF712
• notification-warning-fg — the foreground color for a warning notification.
  • Value type: String
  • Default value: #FFFFFF
• statusbar-bg — the background color of the statusbar.
  • Value type: String
  • Default value: #000000
• statusbar-fg — the foreground color of the statusbar.
  • Value type: String
  • Default value: #FFFFFF
• statusbar-h-padding — the horizontal padding of the statusbar and the notificationbar.
  • Value type: Integer
  • Default value: 8
• statusbar-v-padding — the vertical padding of the statusbar and the notificationbar.
  • Value type: Integer
  • Default value: 2
• window-height — the window height on startup.
  • Value type: Integer
  • Default value: 600
• window-width — the window width on startup.
  • Value type: Integer
  • Default value: 800
• abort-clear-search — whether the search results should be cleared on abort.
  • Value type: Boolean
  • Default value: true
• adjust-open — which auto adjustment mode gets used when a document is loaded. Possible options are "best-fit" and "width".
  • Value type: String
  • Default value: best-fit
• page-mode — the default page sizing mode when you open a document. Possible options are "none", "equal_width", and "equal_height". When set to "equal_width", all pages are scaled to match the width of the current page. When set to "equal_height", all pages are scaled to match the height of the current page. 🦋
  • Value type: String
  • Default value: none
• advance-pages-per-row — whether the number of pages per row should be honored when advancing a page.
  • Value type: Boolean
  • Default value: false
• continuous-hist-save — tells zathura whether to save document history at each page change, or only when closing a document.
  • Value type: Boolean
  • Default value: false
• database — the database backend used for bookmarks and input history. Possible values are "sqlite" and "null". If "null" is used, bookmarks and input history will not be stored (ngl, that's the point of it).
  • Value type: String
  • Default value: sqlite
• dbus-raise-window — whether zathura's window should be raised when it receives certain commands via D-Bus.
  • Value type: Boolean
  • Default value: true
• dbus-service — en/disables the D-Bus service. > If the service is disabled, SyncTeX forward synchronization is not available. so like, know the tradeoff 💀
  • Value type: Boolean
  • Default value: true
• double-click-follow — whether a double or single click on a link should trigger follow.
  • Value type: Boolean
  • Default value: true
• filemonitor — the file monitor backend used to check for changes in files. Possible values are "glib", "signal" (if signal handling is supported), and "noop". The "noop" file monitor does not trigger reloads.
  • Value type: String
  • Default value: glib
• first-page-column — the column in which the first page will be displayed. This setting is stored separately for every value of pages-per-row, following this pattern: <1 page per row>:[<2 pages per row>[: ...]]. The last value in the list gets used for every other number of pages per row if it isn't set explicitly.

Per default, the first column is set to 2 for double-page layout, i.e. the value is set to 1:2. A value of 1:1:3 would put the first page in dual-page layout in the first column, and for layouts with more columns the first page would go in the 3rd column. 🧚

• Value type: String
• Default value: 1:2

• highlight-active-color — the color used to show the currently selected highlighted element (e.g: current search result).
  • Value type: String
  • Default value: rgba(0,188,0,0.5)
• highlight-color — the color used for highlighting parts of the document (e.g.: showing search results).
  • Value type: String
  • Default value: rgba(159,251,0,0.5)
• highlight-fg — the color used for text when highlighting parts of the document (e.g.: the number for links).
  • Value type: String
  • Default value: rgba(0,0,0,0.5)
• highlighter-modifier — the modifier that has to be pressed together with the left mouse button to draw the highlighter. Possible values are "shift", "ctrl" and "alt".
  • Value type: String
• Default value: shift
• incremental-search — turns incremental search on/off, aka the "you search WHILE you type" behaviour ✨
  • Value type: Boolean
  • Default value: true
• index-active-bg — the background color of the element you've got selected in index mode 🎀
  • Value type: String
  • Default value: #9FBC00
• index-active-fg — the foreground (text) color of that selected element in index mode 💅
  • Value type: String
  • Default value: #232323
• index-bg — background color of index mode itself, the whole vibe 🦋
  • Value type: String
  • Default value: #232323
• index-fg — foreground color of index mode, so your text is actually readable 😭
  • Value type: String
  • Default value: #DDDDDD
• jumplist-size — the max number of positions it'll remember in the jumplist, no cap 🧚
  • Value type: Integer
  • Default value: 2000
• link-hadjust — on/off for aligning to the LEFT internal link targets, like the ones from the index 👑
  • Value type: Boolean
  • Default value: true
• link-zoom — on/off for whether following links is even allowed to change your zoom 🫶
  • Value type: Boolean
  • Default value: true
• nohlsearch — Dis/Enables highlighting of search results (read that carefully bestie, it's Dis/Enables, so true = no highlight) 🔍
  • Value type: Boolean
  • Default value: false
• open-first-page — always open documents on the first page. If you disable it, zathura jumps to the last remembered position instead 🥲
  • Value type: Boolean
  • Default value: false
• open-link-confirm — pops a lil confirmation dialog whenever you open external links, which honestly? iconic safety feature 🛟
  • Value type: Boolean
  • Default value: true
• page-cache-size — the max number of pages that can live in the page cache. When the cache is full and a new page that isn't cached becomes visible, the least recently viewed page in the cache gets evicted to make room for the new one 🌀

⚠️ Big values for this one are NOT recommended — you'll eat up a significant portion of system memory. Fr fr, don't.

• Value type: Integer
• Default value: 15

• page-v-padding — vertical page padding, aka the vertical gap in pixels between each rendered page 📏
  • Value type: Integer
  • Default value: 1
• page-h-padding — horizontal page padding, aka the horizontal gap in pixels between each rendered page 📐
  • Value type: Integer
  • Default value: 1
• page-right-to-left — whether pages in multi-column view start from the right side, for all my RTL besties 💜
  • Value type: Boolean
  • Default value: false
• page-thumbnail-size — the maximum size in pixels of the thumbnail kept in the thumbnail cache per page. The thumbnail is scaled for a quick preview during zooming before the page is rendered. When the page is rendered, the result is saved as the thumbnail only if the size is no more than this value. Bigger value = better quality, but longer zoom delay and more system memory 😮‍💨
  • Value type: Integer
  • Default value: 4194304 (4M)
• pages-per-row — how many pages get rendered next to each other in a row 👯‍♀️
  • Value type: Integer
  • Default value: 1
• recolor — En/Disables recoloring 🎨
  • Value type: Boolean
  • Default value: false
• recolor-adjust-lightness — En/Disables adjusting lightness when recoloring ✨
  • Value type: Boolean
  • Default value: false
• recolor-darkcolor — the color value used to represent dark colors in recoloring mode 🌑
  • Value type: String
  • Default value: #FFFFFF
• recolor-keephue — En/Disables keeping the original hue when recoloring 🌈
  • Value type: Boolean
  • Default value: false
• recolor-lightcolor — the color value used to represent light colors in recoloring mode ☀️
  • Value type: String
  • Default value: #000000
• recolor-reverse-video — defines if the original image colors should be kept while recoloring 🙈
  • Value type: Boolean
  • Default value: false
• render-loading — defines if the "Loading..." text should be displayed while a page is rendered ⏳
  • Value type: Boolean
  • Default value: true
• render-loading-bg — background color used for that "Loading..." text 🎀
  • Value type: String
  • Default value: #FFFFFF
• render-loading-fg — foreground color used for the "Loading..." text 🖤
  • Value type: String
  • Default value: #000000
• scroll-full-overlap — the proportion of the current viewing area that should still be visible after scrolling a full page 🔁
  • Value type: Float
  • Default value: 0
• scroll-hstep — the horizontal step size of scrolling when you call the scroll command once ↔️
  • Value type: Float
  • Default value: -1
• scroll-step — the step size of scrolling when you call the scroll command once ↕️
  • Value type: Float
  • Default value: 40
• scroll-page-aware — defines if scrolling by half or full pages stops at page boundaries 🛑
  • Value type: Boolean
  • Default value: false
• scroll-wrap — defines if the last/first page should be wrapped 🔄
  • Value type: Boolean
  • Default value: false
• search-hadjust — En/Disables horizontally centered search results 🎯
  • Value type: Boolean
  • Default value: true
• selection-clipboard — which X clipboard your mouse-selected data gets written to. When it's "clipboard", selected data goes to the CLIPBOARD clipboard and you can paste it with Ctrl+v. When it's "primary", selected data goes to the PRIMARY clipboard and you can paste it with the middle mouse button, or Shift+Insert. The value "false" can be used to disable copying to the clipboard entirely 🙅‍♀️
  • Value type: String
  • Default value: primary
• selection-notification — defines if a notification should show up after you select text 🔔
  • Value type: Boolean
  • Default value: true
• signature-error-color — the background color when displaying additional information for signatures with errors 🚨
  • Value type: String
  • Default value: rgba(92%,11%,14%,0.9)
• signature-success-color — the background color when displaying additional information for valid signatures ✅
  • Value type: String
  • Default value: rgba(18%,80%,33%,0.9)
• signature-warning-color — the background color when displaying additional information for signatures with warnings ⚠️
  • Value type: String
  • Default value: rgba(100%,84%,0%,0.9)
• single-page-mode — defines if documents should be opened in single-page view mode 📄
  • Value type: Boolean
  • Default value: false
• show-directories — defines if directories should be displayed in completion 🗂️
  • Value type: Boolean
  • Default value: true
• show-hidden — defines if hidden files and directories should be displayed in completion 👻
  • Value type: Boolean
  • Default value: false
• show-recent — how many recent files should be displayed in completion. Negative value = all recent files shown. 0 = no recent files shown 🕰️
  • Value type: Integer
  • Default value: 10
• show-signature-information — defines whether additional information on signatures embedded in documents should be displayed 📝
  • Value type: Boolean
  • Default value: false
• statusbar-basename — use the basename of the file in the statusbar 🏷️
  • Value type: Boolean
  • Default value: false
• statusbar-home-tilde — displays a short version of the file path in the statusbar, one that replaces $HOME with ~ 🏠
  • Value type: Boolean
  • Default value: false
• statusbar-page-percent — displays (current page / total pages) as a percent in the statusbar 💯
  • Value type: Boolean
  • Default value: false
• synctex — En/Disables SyncTeX backward synchronization support 🧵
  • Value type: Boolean
  • Default value: true
• synctex-edit-modifier — the modifier you gotta hold together with the left mouse button to trigger SyncTeX backward synchronization. Possible values are "shift", "ctrl" and "alt" 🖱️
  • Value type: String
  • Default value: ctrl
• synctex-editor-command — the command executed for SyncTeX backward synchronization 🧑‍💻
  • Value type: String
  • Default value: (empty)
• vertical-center — centers the screen at the vertical midpoint of the page by default 🎯
  • Value type: Boolean
  • Default value: false
• window-decoration — show window decorations 🪟
  • Value type: Boolean
  • Default value: true
• window-title-basename — uses the basename of the file in the window title 🏷️
  • Value type: Boolean
  • Default value: false
• window-title-home-tilde — displays a short version of the file path in the window title, the one that replaces $HOME with ~ 🏠
  • Value type: Boolean
  • Default value: false
• window-title-page — displays the page number in the window title 🔢
  • Value type: Boolean
  • Default value: false
• zoom-center — En/Disables horizontally centered zooming 🔍
  • Value type: Boolean
  • Default value: false
• zoom-max — okay bestie, this one sets the maximum percentage that the zoom level is allowed to reach 💅 it's literally the ceiling, no cap.
  • Value type: Integer
  • Default value: 1000
• zoom-min — and this is the minimum percentage the zoom level can go down to 🦋 the floor, the lower limit, the "don't shrink past this" vibe.
  • Value type: Integer
  • Default value: 10
• zoom-step — defines how much percent gets zoomed in or out on each command 👑 so every zoom action moves by this amount, iconic and simple.
  • Value type: Integer
  • Default value: 10

---

👀 SEE ALSO 👀

• zathura(1) — go read the main character's manual too, iykyk 🫶

✍️ Author ✍️

pwmt.org — yes, that's the author, periodt 💖

©️ Copyright ©️

2009-2026, pwmt.org — all the rights, all the years, all the credit 🌸

---

And that's the whole page, bestie 🎀 it's from 2026.10.23 (the source/version) and dated 2026-10-23, with the page name ZATHURARC(5) living its best life at the bottom. Slay, you made it to the end 💜