Haiku Fonts: System Defaults, Installation Scope, and Testing

Haiku’s font preferences control system-wide typography used by native applications. The Appearance panel defines plain, bold, and fixed fonts and sizes, plus a separate menu font. Installing a new font changes the available choices; it does not guarantee that every application will immediately redraw with it or that a selected family contains every glyph an application needs.

Font management has two distinct layers. System font preferences select defaults for user-interface roles. Individual applications can choose other BFont instances for document content, code editors, or custom drawing. The BFont API article covers measurement and baselines; this guide is about installing families, choosing system roles, and verifying fallback without destabilizing layouts.

Record the current appearance state

Before changing fonts, record Haiku revision, architecture, Appearance settings, display scale/resolution, and the applications where the problem appears. A font substitution can expose a layout defect, but it can also make text clearer or wider. One application displaying a missing glyph does not prove the system font installation failed; the application’s chosen font, file encoding, and fallback path all matter.

Open Deskbar → Preferences → Appearance and use the Fonts section to choose plain, bold, fixed, and menu fonts. The exact font names vary by installed packages. Use the preview and test a real application rather than relying only on a font sample. Terminal and code editors need a legible fixed-width face; menus and labels need sizes that fit localized strings.

Change one role at a time. If a UI becomes unreadable, use the panel’s Revert/Defaults controls instead of manually editing internal settings files. Current user-guide documentation lists ~/config/settings/system/app_server/fonts as a settings path, but those files are implementation state; prefer the supported panel unless diagnosing a reproducible configuration defect.

Install a package-managed font first

When a font is distributed as a Haiku package, install it through HaikuDepot or pkgman so package metadata, updates, and uninstall behavior remain coherent. Verify the package’s exact family names and licensing information from its publisher. A package can contain multiple styles or variable families; do not assume the package title equals the font menu’s family string.

After installation, reopen Appearance if the font list has not refreshed. The current user guide says newly installed fonts can be used without a reboot, but applications that are already running may have cached font lists or metrics. Close and reopen the affected application before concluding that the system failed to discover the font.

Do not unpack a Linux package or copy a font into a system directory merely because its extension is .ttf or .otf. Check the package source, supported format, and destination first. A malformed or incompatible font can affect rendering or application stability. Keep the original font package so a bad installation can be removed cleanly.

Use non-packaged folders only when needed

For a font that does not arrive in a regular .hpkg, the Haiku User Guide documents non-packaged font directories organized by type. For example, TrueType fonts can be placed under /boot/system/non-packaged/data/fonts/ttfonts/ to make them available system-wide, or under /boot/home/config/non-packaged/data/fonts/ttfonts/ for the current user. The guide also names otfonts, psfonts, and ttfonts for corresponding font types.

Prefer the user-specific location for a personal test. It limits the change’s scope and avoids requiring administrator-level modification. Use the system-wide non-packaged tree only when the font should be available to all users and the system administrator intends that state. Do not write into package-managed /boot/system/data/fonts content.

Keep a small test directory with only the candidate font. Verify the family and style name in Appearance, then test representative glyphs and weights. If multiple font files declare the same family/style, conflicts can be confusing; install one candidate at a time and record which file provided it. Remove a test font by moving it out of the documented non-packaged folder and reopening the relevant applications.

Understand fallback and missing glyphs

A family can be installed and selectable while lacking glyphs for the text being displayed. Applications may use fallback fonts per character or script. A missing ideograph, symbol, emoji, or combining mark can therefore be an asset-coverage issue rather than a broken font installation. Test the actual language/script and text shaping behavior, not just Latin letters.

Plain, bold, fixed, and menu roles are defaults, not global commands that override every application. An application can deliberately request another font or preserve a document-specific font. If a single app differs, inspect its settings and restart it before changing the system defaults. If every native app changes but one ported app does not, the ported toolkit may manage fonts separately.

Text width affects layout. A font change can widen buttons, change line breaks, and move labels even when point size is identical. Applications should use preferred-size/layout APIs and measure actual text with the font they draw. Do not “fix” a clipped label by arbitrarily shrinking the global font; repair the component or report the app-specific geometry issue.

Diagnose unreadable or inconsistent rendering

If the font does not appear in Appearance, confirm its type-specific folder or package installation, then reopen the preference panel. Check permissions and whether the system supports the file. If the font appears but one app still uses another face, restart it and verify its own font settings. If only certain characters are missing, test another family with the needed glyph range and record the exact text/script.

If text is blurry or appears too dark, inspect the Appearance panel’s antialiasing and glyph-hinting settings separately from font choice. Those settings alter rasterization and can improve one size while harming another. Change one setting at a time and test the same window, resolution, and scale. Subpixel antialiasing can introduce colored edges; choose the mode that is comfortable on the actual display.

If a system setting file appears damaged, back it up and use Appearance to restore defaults. Do not copy another user’s /boot/home/config/settings/system/app_server/fonts file over the current one without understanding its scope and format. Reverting in the panel is the controlled recovery path.

Acceptance matrix

Test a native Preferences panel, Terminal, a text editor, a menu, a dialog with long labels, and a multilingual document. Check plain, bold, fixed, and menu roles. Verify Latin, accented characters, the target script, and a symbol outside the common basic range. Confirm existing windows redraw after restart and that their layout remains usable.

For a non-packaged font, verify the intended scope by checking the user and system locations separately. Test removal and recovery. For a package, confirm version and package ownership in HaikuDepot/pkgman, then verify that uninstall returns the font selection to a valid fallback. Do not leave the desktop dependent on a font package that is about to be removed.

For repeatable diagnosis, keep a short test string that includes the characters and scripts that failed, plus the intended family and style. Record the selected Appearance role, the actual application, and whether restarting that application changed the result. Compare the same string in a native control, Terminal, and the affected program. If only one component differs, investigate its toolkit or document font before changing system-wide defaults. This keeps a local rendering defect from becoming a desktop-wide preference change.

When moving a font between user and system scope, remove the duplicate copy from the old location and reopen the preference panel before drawing conclusions. Two files can advertise the same family/style and make the selected source ambiguous. For managed packages, use the package manager’s installed-file and version information instead of manually deleting files from the package tree. After recovery, recheck both the chosen default and fallback behavior so a removed font does not silently leave an unavailable family selected.

The safest Haiku font workflow is to use Appearance for system roles, package-managed fonts where possible, and documented non-packaged folders for controlled exceptions. Verify fallback with the actual content and restart affected applications before diagnosing a platform failure. This keeps typography choices reversible and separates font discovery from application layout bugs.

Related:

Sources: