← Otto User GuideConfiguration

Otto uses TOML configuration files to customize your experience. This page explains how config files are loaded and merged; the individual settings are documented in their own pages.

Configuration Files

Otto searches for configuration files in the following order (later files override earlier ones):

System config: /etc/otto/config.toml
- System-wide defaults managed by administrators
- Lowest priority
- Not created by the package. Otto’s packages install a commented example at /etc/otto/config.example.toml and never write config.toml itself, so nothing an administrator puts there can be moved aside by an upgrade or by switching between the otto, otto-git and otto-nightly-bin packages. Copy the example to config.toml to start from it.
User config: $XDG_CONFIG_HOME/otto/config.toml
- Per-user configuration (defaults to ~/.config/otto/config.toml)
- Follows XDG Base Directory specification
- Recommended location for user customization
Local override: ./otto_config.toml
- Config file in the current working directory
- Useful for development and testing
Backend-specific: ./otto_config.{backend}.toml
- Backend-specific overrides (e.g., otto_config.winit.toml, otto_config.udev.toml)
- Highest priority
- Useful for maintaining different settings per backend during development

Values from higher-priority files are merged recursively into lower-priority ones, so you only need to specify the options you want to override.

Config files are read once, when the session starts: an edit takes effect on the next login.

Which file gets written

Changes made from the Settings app — or from the desktop itself, such as dragging the dock handle — are written to the highest-priority file that exists, because that is the one whose values actually take effect. With no otto_config.toml around, that is ~/.config/otto/config.toml, and it is created if it is not there yet. The system-wide /etc/otto/config.toml is never written.

This is worth knowing when a setting appears not to stick. A leftover otto_config.toml in the directory the session was started from — the current directory is the home directory for a normal login, and the checkout for cargo run — overrides ~/.config/otto/config.toml for every key it sets, and quietly becomes the file the Settings app edits. Otto logs a warning at startup when the writable file is not your own config; delete the stray file, or the keys it repeats, to go back to configuring from ~/.config/otto.

Getting Started

# Create user config directory
mkdir -p ~/.config/otto

# Copy the example config (contains all options with documentation)
cp otto_config.example.toml ~/.config/otto/config.toml

# Edit as needed
$EDITOR ~/.config/otto/config.toml

Configuration Topics

Topic	Description
Display	Scaling, display profiles, monitor arrangement, virtual outputs, layer shell zones
Theming	Theme scheme, accent color, fonts, background, cursors, icons
Input	Keyboard layout and repeat, touchpad, pointer acceleration
Keyboard Shortcuts	Binding syntax and the complete action list
Dock	Dock appearance, bookmarks, autohide, magnification
Top Bar	Clock format, tray, global menus (`topbar.toml`)
Audio	Sound effects and sound themes
Power Management	Lid switch, power button, suspend, clamshell
Lock Screen	Locker command, idle auto-lock, PAM setup
Login Greeter	`--login` mode and the greeter command
Night Shift	Color temperature and brightness control
Autostart	exec_once, XDG autostart, systemd integration
Clipboard	Clipboard persistence and managers

For everything else — how to use the desktop rather than configure it — start from the User Guide index.

Tips

Start with the example — copy otto_config.example.toml to ~/.config/otto/config.toml and modify as needed.
Use XDG paths — ~/.config/otto/config.toml persists across updates.
System-wide defaults — administrators can set defaults in /etc/otto/config.toml.
Backend-specific settings — use otto_config.winit.toml in the current directory for development/testing.
Scaling — adjust screen_scale based on your display DPI (1.0 for 96 DPI, 2.0 for HiDPI).

Troubleshooting

Configuration not loading:

Verify the TOML syntax (matching brackets, quotes, commas).
Check Otto’s log output for parsing errors and which config files were loaded.
Ensure the config file is in one of the searched locations listed above.

An edit to /etc/otto/config.toml does nothing:

The user config wins. Check whether ~/.config/otto/config.toml sets the same key — a key present there shadows the system file even if you never typed it, since older builds copied the whole [dock] table into it (see Dock).
Restart the session: config is only read at startup.

Icon/cursor theme not found:

Verify the theme is installed: ls /usr/share/icons/ ~/.local/share/icons/
Theme names are case-sensitive.
Some themes may require additional packages.

Keyboard shortcuts not working:

Modifiers are Ctrl, Alt, Shift and Logo (aliases accepted, case-insensitive).
An unparsable trigger or action is skipped with a warning, not an error — grep the log for skipping shortcut.
Some shortcuts may conflict with an application’s shortcut inhibitor.

Touchpad settings ignored:

Settings only apply to touchpad devices, not mice.
Some hardware may not support all features.
Check libinput capabilities for your device.

For a fuller list, see Troubleshooting.