OpenBSD Desktop Environments

Synopsis #

OpenBSD supports lightweight window managers and full desktop environments. Choose a window manager or desktop, and configure the tools it needs.

Set up X, graphics hardware, and input devices using the X11 chapter before choosing a desktop.

Window Managers #

A window manager (WM) controls the placement, appearance, and behavior of application windows in the X Window System.

Window managers generally fall into the following categories:

• Stacking (floating): Windows can overlap freely and are usually moved/resized with the mouse.
• Tiling: Windows are placed side by side in a non-overlapping layout, usually managed by keyboard shortcuts.
• Dynamic: Offers tiling, floating, and tabbed modes that can switch dynamically.

Common Window Managers on OpenBSD #

The following table provides an overview of window managers included in the base X sets or available as packages:

The three base window managers require no package installation. Entries with package names can be installed with pkg_add(1). Configure startup using .xinitrc or .xsession.

Floating window managers allow applications to overlap. The title bars and desktop controls differ:

Example for i3:

doas pkg_add i3
echo 'exec i3' > ~/.xinitrc
startx

Awesome #

Awesome combines tiling and floating layouts with Lua configuration. Its tags can group windows by task without requiring a separate desktop environment.

doas pkg_add awesome

Create the personal configuration from the packaged example before starting the session:

mkdir -p ~/.config/awesome
cp /usr/local/share/examples/awesome/rc.lua ~/.config/awesome/rc.lua

After saving the existing session file, use exec /usr/local/bin/awesome as the final line of ~/.xsession for xenodm(1), or ~/.xinitrc for startx(1). Make .xsession executable and log out before starting the new session. See X session configuration .

The default modifier is Super, usually the Windows key. Super+Return opens a terminal, Super+Space changes layout, Super+j and Super+k change focus, and Super+1 through Super+9 select tags. Super+Ctrl+Space toggles floating for the selected window. Super+Shift+q quits Awesome.

In ~/.config/awesome/rc.lua, change the terminal setting to select an installed terminal, for example terminal = "xterm". Check Lua syntax before reloading:

awesome -k -c ~/.config/awesome/rc.lua

Super+Ctrl+r restarts Awesome after a configuration change. Keep a working copy of the configuration; a syntax check cannot detect every runtime error. Use the installed awesome(1) manual and Awesome’s configuration documentation for further changes.

Enlightenment E16 #

OpenBSD’s enlightenment package provides E16, the independently maintained predecessor of the newer Enlightenment desktop. It is a themed X window manager with menus, a desktop pager, and graphical settings.

doas pkg_add enlightenment

After saving the existing session file, use exec /usr/local/bin/e16 as the final line of ~/.xsession or ~/.xinitrc. Make .xsession executable when using xenodm, then log out and log in again.

Use the background menus to launch applications and open settings. The pager switches between desktops and shows window positions. Start with the installed theme and adjust appearance or desktop settings through the menus; E16 stores personal settings under ~/.e16/.

Use the session menu to log out. If the new session fails, inspect ~/.xsession-errors and restore the previous session file. See the E16 project for its interface and theme documentation.

Plan 9 Tools and suckless #

For a different mouse-driven workflow, use Plan 9 tools on OpenBSD : the plan9port package includes rio, Acme, Sam, and 9term. The editors also run inside an existing desktop.

For a small keyboard-driven session, build a desktop with suckless tools , combining dwm, dmenu, st, surf, and a display locker.

Desktop Environments #

Desktop environments include a window manager, graphical utilities, file manager, terminal emulator, and configuration panels. These offer a more complete experience but require more system resources.

Xfce #

Xfce is a popular choice on OpenBSD due to its low resource usage.

doas pkg_add xfce
echo 'exec startxfce4' > ~/.xinitrc

GNOME #

GNOME provides an integrated desktop with an application overview and workspace controls.

doas pkg_add gnome
doas rcctl enable messagebus gdm
doas rcctl order messagebus
doas rcctl start messagebus
# Stop and disable the previous display manager before starting GDM.
doas rcctl start gdm

Use GDM for GNOME session tracking and screen locking. Additional configuration is documented in /usr/local/share/doc/pkg-readmes/gnome.

KDE Plasma #

KDE Plasma provides a desktop with panels, widgets, and graphical settings.

doas pkg_add kde-plasma

Before launching startplasma-x11, follow /usr/local/share/doc/pkg-readmes/kde-plasma to configure the kde login class, runtime directory, D-Bus session, and startup script. Use .xinitrc with startx(1) or .xsession with xenodm(1).

Due to its modular design, KDE requires more packages and memory.

Display Managers (Login Managers) #

A display manager (or login manager) is a graphical application that starts X and presents a user login screen. It replaces the need to use startx manually.

Display managers typically use .xsession instead of .xinitrc.

xenodm #

xenodm is included in the base system and provides a minimal graphical login.

Enable it at boot:

doas rcctl enable xenodm
doas rcctl start xenodm

Customizations are found in /etc/X11/xenodm/.

Other Display Managers #

The following display managers are available via packages:

• GDM (GNOME): pkg_add gdm

Enable one as follows:

doas rcctl enable gdm
doas rcctl start gdm

For xenodm, select the session using the user’s .xsession; GDM instead selects an installed desktop session:

echo 'exec startxfce4' > ~/.xsession

Session Management #

Use .xinitrc when launching X with startx. Use .xsession when using a display manager like xenodm; GDM selects installed desktop sessions.

To share configuration, .xinitrc may source .xsession:

echo 'exec ~/.xsession' > ~/.xinitrc

Multi-Monitor Setup #

The xrandr tool can be used to configure screen layouts dynamically.

Example:

xrandr --output eDP-1 --primary --output HDMI-1 --right-of eDP-1 --auto

Add such commands to .xinitrc or .xsession to apply settings on login.

Fonts and Appearance #

Fonts for desktop environments and applications may be installed as follows:

doas pkg_add noto-fonts

Font rendering settings can be adjusted using ~/.Xresources or ~/.config/fontconfig/fonts.conf.

More information is available in the X11 chapter.

Troubleshooting #

• If startx fails, check .xsession-errors in the user’s home directory.
• Ensure session commands (e.g., startxfce4) are installed and correct.
• Make sure required daemons are running:

doas rcctl enable messagebus
doas rcctl start messagebus
# polkit is activated through D-Bus; it has no rcctl service.

Web Browsers #

OpenBSD supports several web browsers, ranging from full-featured GUI-based browsers to minimalist and text-based alternatives. Each is available through the ports system and may be installed via pkg_add.

Resource Limits and Browser Stability #

By default, OpenBSD enforces strict per-process memory limits. The default soft limit on data segment size (datasize-cur) is 1536 MB (1.5 GB) per process. Modern web browsers such as Firefox and Chromium can exceed this threshold, especially on complex pages or with multiple tabs, resulting in a crash or unexpected termination.

To increase the limit for a login class or user:

1. Edit /etc/login.conf:

   default:\
   	:datasize-cur=4096M:\
   	:datasize-max=4096M:\
   	:\
   	...
   

2. Rebuild the login database:

   doas cap_mkdb /etc/login.conf
   

3. Log out and back in for changes to take effect.

Ensure adequate system RAM and swap are available before raising memory limits.

See browser troubleshooting for crashes, profile failures, and graphics problems.

Full-Featured Browsers #

These browsers are recommended for most users and support modern web standards including JavaScript, CSS, multimedia playback, and extensions.

Firefox #

Firefox is available as a package.

doas pkg_add firefox

Variants include:

• firefox-esr: Extended Support Release
• firefox-i18n: Adds international language packs

Ensure supporting services are enabled:

doas rcctl enable messagebus
doas rcctl start messagebus
doas rcctl enable avahi_daemon
doas rcctl start avahi_daemon

Chromium #

Chromium is an open-source browser from the same codebase as Google Chrome.

doas pkg_add chromium

Chromium is not available on all hardware platforms due to sandboxing or library dependencies. Check pkg_info -Q chromium for architecture availability.

Other GUI Browsers #

qutebrowser #

Minimal Qt-based browser with Vim-style keybindings.

doas pkg_add qutebrowser

The package tools install its required dependencies.

epiphany #

GNOME’s default WebKitGTK browser.

doas pkg_add epiphany

Integrates well with GNOME sessions and supports bookmarks and tabs.

surf #

Minimal WebKit-based browser developed by suckless.org.

doas pkg_add surf

No tabs by default; may be used with tabbed for multiple windows.

Lightweight and Text-Based Browsers #

These browsers consume fewer resources and may be used over SSH or in low-memory environments.

netsurf #

Lightweight graphical browser with its own rendering engine.

doas pkg_add netsurf

Does not support JavaScript or complex HTML5 features.

lynx, w3m, links #

Text-mode browsers used in terminals or headless environments.

doas pkg_add lynx w3m links

Useful for reading documentation, accessing webmail, or browsing lightweight sites.

Locale and Font Configuration #

Browsers require proper locale and font settings for multilingual display and antialiasing.

Set locale as needed:

export LANG=en_US.UTF-8
firefox

Install font packages:

doas pkg_add noto-fonts

Further configuration options are discussed in the X11 chapter.

Multimedia Support #

Some browsers rely on external tools for video and audio playback. Install the following if needed:

doas pkg_add ffmpeg gst-plugins-good gst-plugins-bad

Check browser preferences to enable or disable hardware acceleration.

Troubleshooting #

• Sudden browser exits may indicate a memory limit was exceeded (datasize-cur).
• Missing fonts or symbols: verify font packages and fontconfig setup.
• Video playback failure: check for ffmpeg, gstreamer, or sndio issues.

Development Tools #

OpenBSD includes many tools suitable for software development, ranging from compilers and debuggers to graphical editors and IDEs. Most are installed via packages, while some are included in the base system.

Compilers and Build Tools #

OpenBSD ships with the clang and lld toolchain from LLVM in base. It supports C, C++, and Objective-C.

Additional build tools are available via packages:

doas pkg_add gmake cmake autoconf automake libtool pkgconf

These are often required when building software from source.

For Rust or Go development:

doas pkg_add rust go

For Java:

doas pkg_add openjdk

Version Control Systems #

To work with source repositories:

doas pkg_add git mercurial subversion

• git: Most commonly used
• cvs: Required for OpenBSD source trees
• subversion, mercurial: Less common, but available

Editors and IDEs #

The following graphical editors and IDEs are available:

Example installation:

doas pkg_add geany

geany can be launched from a terminal or desktop menu.

Terminal Emulators #

While not strictly development tools, terminal emulators are often used during development. In addition to xterm from base, these are available:

• st (from suckless): pkg_add st
• rxvt-unicode: pkg_add rxvt-unicode
• alacritty: pkg_add alacritty
• kitty: pkg_add kitty

Choose one that integrates well with the chosen desktop environment and supports required features (e.g., truecolor, Unicode, clipboard).

Debugging Tools #

Debuggers are available from packages; base includes tracing tools such as ktrace and kdump:

doas pkg_add gdb lldb

Valgrind and strace are not in the OpenBSD 8.0 amd64 package set.

For graphical debugging, ddd is also available:

doas pkg_add ddd

Documentation and Manual Pages #

Most OpenBSD development tools are documented in manual pages.

To find a man page:

man clang
man git

Additional documentation may be installed under /usr/local/share/doc/ or accessed online via project websites.

Language Servers and Autocompletion #

Modern editors like neovim, emacs, and lite-xl can integrate with Language Server Protocol (LSP) backends for intelligent code completion, linting, and refactoring.

Install with:

doas pkg_add py3-python-lsp-server node clang-tools-extra

• py3-python-lsp-server: Python LSP
• clangd: C/C++ language server
• typescript-language-server: for JavaScript/TypeScript (requires node)

Configuration is editor-specific.

Office Productivity #

Install an office suite or individual document and spreadsheet applications with pkg_add.

LibreOffice #

LibreOffice is the most complete office suite available on OpenBSD. It includes:

• Writer: Word processor
• Calc: Spreadsheet editor
• Impress: Presentation creator
• Draw: Vector graphics
• Math: Equation editor
• Base: Database front-end

Install it with:

doas pkg_add libreoffice

Launch with:

libreoffice

LibreOffice supports ODF and Microsoft Office file formats (.docx, .xlsx, .pptx). It integrates with most desktop environments.

Calligra Suite #

The KDE office suite is also available:

doas pkg_add calligra

Includes words, sheets, stage, and other components. Uses Qt-based UI and integrates well with KDE environments.

AbiWord and Gnumeric #

For systems with limited resources, standalone applications are available:

doas pkg_add abiword gnumeric

• abiword: Lightweight word processor
• gnumeric: Lightweight spreadsheet editor

Both are GTK-based and have a smaller footprint than LibreOffice.

PDF Editing #

While most office suites can export to PDF, editing PDF files requires separate tools.

• pdfarranger: GUI to merge/split pages — pkg_add pdfarranger
• xournalpp: Annotate and draw on PDFs — pkg_add xournalpp

PDF viewing is described in the Document Viewers section.

Markdown and Text-Based Formats #

For users preferring lightweight workflows, tools for writing in plain text or Markdown are available:

• ghostwriter: Minimalist Markdown editor — pkg_add ghostwriter

• zathura or lowriter for previewing output

• Pandoc for format conversion:

  doas pkg_add pandoc
  

Example:

pandoc -o report.pdf report.md

Document Viewers #

OpenBSD supports a variety of document viewing applications, ranging from minimal PDF readers to feature-rich multi-format tools. These applications are available through the ports system and can be installed with pkg_add.

PDF Viewers #

zathura #

Minimal, keyboard-driven PDF viewer with plugin support.

doas pkg_add zathura zathura-pdf-poppler

• Vim-like keybindings
• Plugin-based architecture
• Supports bookmarks and searching

To open a file:

zathura document.pdf

mupdf #

Ultra-lightweight PDF viewer.

doas pkg_add mupdf

• Fast and resource-efficient
• Minimal GUI
• Keyboard-based navigation

qpdfview #

Tabbed PDF viewer with optional support for DjVu and PostScript.

doas pkg_add qpdfview

• Supports annotations and searching
• Suitable for graphical desktop use

xpdf #

Traditional, minimal PDF viewer using the Motif toolkit.

doas pkg_add xpdf

Simple and portable, but lacks modern features.

PostScript and DjVu #

gv #

Ghostview frontend for PostScript files.

doas pkg_add gv

Relies on Ghostscript (pkg_add ghostscript) for rendering.

djview #

Graphical viewer for DjVu files (scanned document format).

doas pkg_add djview

Alternatively, zathura-djvu provides DjVu support via plugin.

Image Viewers #

While not strictly document viewers, image viewers are often used for scanned files or document images.

• feh: Lightweight and scriptable — pkg_add feh
• sxiv: Simple X image viewer — pkg_add sxiv
• nomacs: More advanced, Qt-based — pkg_add nomacs

EPUB and eBook Viewers #

foliate #

Modern GTK-based eBook reader supporting EPUB.

doas pkg_add foliate

Features include:

• Bookmarking
• Highlighting
• Text-to-speech (if configured)

fbreader #

Lightweight eBook reader supporting EPUB, MOBI, and more.

doas pkg_add fbreader

Document Viewing #

• less for plain text files
• w3m and lynx can be used to view HTML
• mupdf-gl opens PDFs in an OpenGL graphical window and requires a working graphical display

Example:

less README.md
mupdf-gl presentation.pdf

Finance #

OpenBSD provides a selection of financial applications suitable for personal budgeting, small business accounting, and investment tracking. These tools are available through packages and integrate with a variety of desktop environments.

GnuCash #

GnuCash is a full-featured accounting package for personal and small business use.

doas pkg_add gnucash

Features:

• Double-entry accounting
• Scheduled transactions
• Import support for OFX, QIF, and CSV
• Graphical reports and charts

GnuCash uses GTK and integrates well with Xfce or GNOME. It supports encrypted backups and multiple currencies.

HomeBank #

HomeBank is a personal finance manager with a simpler interface.

doas pkg_add homebank

Features:

• Budgeting and trend analysis
• Categorization of expenses
• Import support for QIF and CSV
• Graphical visualization of income and spending

Recommended for users with basic accounting needs.

KMyMoney #

KDE’s personal finance manager.

doas pkg_add kmymoney

Features:

• Familiar ledger interface
• Support for bank and investment accounts
• Reconciliation and scheduled transactions
• OFX/QIF import

Best used in KDE Plasma, but works in other environments.

hledger #

For users who prefer plaintext accounting and version-controlled finances, OpenBSD supports:

doas pkg_add hledger

• hledger: Haskell-based CLI tool with optional TUI/HTTP interface

Example:

2025-07-11 * "Coffee Shop"
  expenses:food:coffee    $3.50
  assets:cash

Plaintext ledgers can be edited, versioned, and processed with scripts.

Spreadsheet-Based Accounting #

For lightweight accounting, spreadsheet software such as gnumeric or libreoffice-calc can be used to maintain personal ledgers or small business finances.

doas pkg_add gnumeric

Templates are available online or can be created manually.