Configuring qutebrowser: Essential Settings and Shortcuts

Configuring qutebrowser: Essential Settings and Shortcuts

Overview

• qutebrowser is a keyboard-driven, minimal web browser configurable via a config file (~/.config/qutebrowser/config.py) and the :set command.
• Configuration focuses on keybindings, privacy, appearance, and behavior to enable fast, mouse-free browsing.

Essential config locations & commands

• config.py: persistent Python-based configuration loaded at startup.
• :set : change settings at runtime (use :set -t to target a specific target like qute://).
• :bind : create or change keybindings temporarily; use config.bind in config.py for permanent bindings.
• :config-source: reload config.py without restarting.

Key settings to change (recommended)

• tabs.show: “multiple”/“always”/“switching” — control tab bar visibility.
• content.javascript.enabled: True/False (or site-specific patterns) — tighten security by disabling JS where not needed.
• content.notifications.enabled: False — block web notifications.
• content.geolocation: False — deny geolocation by default.
• content.cookies.accept: “no-3rdparty” or “never” — limit cookie persistence.
• url.searchengines: map keywords to search engine URLs (e.g., {“DEFAULT”:”https://duckduckgo.com/?q={}”})
• downloads.position: “bottom”/“top” — where the download bar appears.
• editor.command: set external editor (e.g., [“alacritty”,“-e”,“micro”,“{file}”]).

Common config.py snippets

• Bind keys:
  config.bind(‘J’, ‘tab-next’)config.bind(‘K’, ‘tab-prev’)config.bind(‘f’, ‘hint’) # follow links via hints

• Quick search engine:
  config.set(‘url.searchengines’, {‘DEFAULT’:’https://duckduckgo.com/?q={}’, ‘g’:’https://www.google.com/search?q={}‘})

• Disable JavaScript by default, allow per-site:
  config.set(‘content.javascript.enabled’, False)config.set(‘content.javascript.enabled’, True, ‘www.example.com’)

Essential shortcuts (default + recommended)

• f — hint links and follow
• F — hint links and open in new tab
• gg / G — go to top / bottom of page
• d / u — scroll half-page down / up
• H / L — go back / forward in history
• :open — open URL or search
• :tab-select or gT / gt — switch tabs
• :spawn — run external commands (useful for downloads or PDF viewers)
• yy — yank current URL to clipboard
• :set -t -u — view current settings (useful to inspect)

Tips for productivity

• Use hint filtering modes (hint.mode) to quickly target specific element types.
• Map leader keys: e.g., config.bind(’ ‘, ‘set-cmd-text :’) to make command mode faster.
• Create site-specific rules for cookie, JS, and content settings to balance privacy and compatibility.
• Integrate with external tools: mpv for videos, yt-dlp for downloads, external editors for textareas.
• Keep a small, documented config.py with comments and grouped sections for easy maintenance.

Troubleshooting & maintenance

• Run qutebrowser from terminal to see startup errors from config.py.
• Use :config-diff to see runtime differences from defaults.
• When a binding or setting doesn’t work, check for typos and ensure commands use correct names (refer to :help).

Further customization ideas

• Use userscripts and userscripts manager to add functionality.
• Write autoconfig hooks in config.py to apply complex per-site logic.
• Theme qutebrowser by setting fonts, colors, and UI scale in config.py.

If you want, I can generate a ready-to-use config.py example tailored to your preferences (keyboard-only, privacy-focused, or media-heavy).