qutebrowser/doc/help/configuring.asciidoc

Configuring qutebrowser
=======================

IMPORTANT: qutebrowser's configuration system was completely rewritten in
September 2017. This information is not applicable to older releases, and older
information elsewhere might be outdated. **If you had an old configuration
around and upgraded, this page will automatically open once**. To view it at a
later time, use the `:help` command.

Migrating older configurations
------------------------------

qutebrowser does no automatic migration for the new configuration. However,
there's a special link:qute://configdiff[] page in qutebrowser, which will show
you the changes you did in your old configuration, compared to the old defaults.

Other changes in default settings:

- `<Up>` and `<Down>` in the completion now navigate through command history
  instead of selecting completion items. You can get back the old behavior by
  doing:
+
----
:bind -f -m command <Up> completion-item-focus prev
:bind -f -m command <Down> completion-item-focus next
----

- The default for `completion.web_history_max_items` is now set to `-1`, showing
  an unlimited number of items in the completion for `:open` as the new
  sqlite-based completion is much faster. If the `:open` completion is too slow
  on your machine, set an appropriate limit again.

Configuring qutebrowser via the user interface
----------------------------------------------

The easy (but less flexible) way to configure qutebrowser is using its user
interface or command line. Changes you make this way are immediately active
(with the exception of a few settings, where this is pointed out in the
documentation) and are persisted in an `autoconfig.yml` file.

The `autoconfig.yml` file is located in the "config" folder listed on the
link:qute://version[] page. On macOS, the "auto config" folder is used, which is
different from where hand-written config files are kept.

However, **do not** edit `autoconfig.yml` by hand. Instead, see the next
section.

If you want to customize many settings, you can open the link:qute://settings[]
page by running `:set` without any arguments, where all settings are listed and
customizable.

Using the link:commands.html#set[`:set`] command and command completion, you
can quickly set settings interactively, for example `:set tabs.position left`.

To get more help about a setting, use e.g. `:help tabs.position`.

To bind and unbind keys, you can use the link:commands.html#bind[`:bind`] and
link:commands.html#unbind[`:unbind`] commands:

- Binding the key chain "`,`, `v`" to the `:spawn mpv {url}` command:
  `:bind ,v spawn mpv {url}`
- Unbinding the same key chain: `:unbind ,v`
- Changing an existing binding: `bind --force ,v message-info foo`. Without
  `--force`, qutebrowser will show an error because `,v` is already bound.

Key chains starting with a comma are ideal for custom bindings, as the comma key
will never be used in a default keybinding.

Configuring qutebrowser via config.py
-------------------------------------

For more powerful configuration possibilities, you can create a `config.py`
file. Since it's a Python file, you have much more flexibility for
configuration. Note that qutebrowser will never touch this file - this means
you'll be responsible for updating it when upgrading to a newer qutebrowser
version.

The file should be located in the "config" location listed on
link:qute://version[], which is typically `~/.config/qutebrowser/config.py` on
Linux, `~/.qutebrowser/config.py` on macOS, and
`%APPDATA%/qutebrowser/config.py` on Windows.

Two global objects are pre-defined when running `config.py`: `c` and `config`.

Changing settings
~~~~~~~~~~~~~~~~~

`c` is a shorthand object to easily set settings like this:

.config.py:
[source,python]
----
c.tabs.position = "left"
c.completion.shrink = True
----

Note that qutebrowser does some Python magic so it's able to warn you about
mistyped config settings. As an example, if you do `c.tabs.possition = "left"`,
you'll get an error when starting.

See the link:settings.html[settings help page] for all available settings. The
accepted values depend on the type of the option. Commonly used are:

- Strings: `c.tabs.position = "left"`
- Booleans: `c.completion.shrink = True`
- Integers: `c.messages.timeout = 5000`
- Dictionaries:
  * `c.headers.custom = {'X-Hello': 'World', 'X-Awesome': 'yes'}` to override
    any other values in the dictionary.
  * `c.aliases['foo'] = ':message-info foo'` to add a single value.
- Lists:
  * `c.url.start_pages = ["https://www.qutebrowser.org/"]` to override any
    previous elements.
  * `c.url.start_pages.append("https://www.python.org/")` to add a new value.

Any other config types (e.g. a color) are specified as a string. The only
exception is the `Regex` type, which can take either a string (with an `r`
prefix to preserve backslashes) or a Python regex object:

- `c.hints.next_regexes.append(r'\bvor\b')`
- `c.hints.prev_regexes.append(re.compile(r'\bzurück\b'))`

If you want to read a setting, you can use the `c` object to do so as well:
`c.colors.tabs.even.bg = c.colors.tabs.odd.bg`.


Using strings for setting names
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to set settings based on their name as a string, use the
`config.set` method:

.config.py:
[source,python]
----
config.set('content.javascript.enabled', False)
----

To read a setting, use the `config.get` method:

[source,python]
----
color = config.get('colors.completion.fg')
----

Binding keys
~~~~~~~~~~~~

While it's possible to change the `bindings.commands` setting to bind keys, it's
preferred to use the `config.bind` command. Doing so ensures the commands are
valid and normalizes different expressions which map to the same key.

For details on how to specify keys and the available modes, see the
link:settings.html#bindings.commands[documentation] for the `bindings.commands`
setting.

To bind a key:

.config.py:
[source,python]
----
config.bind(',v', 'spawn mpv {url}', mode='normal')
----

If the key is already bound, `force=True` needs to be given to rebind it:

[source,python]
----
config.bind(',v', 'message-info foo', mode='normal', force=True)
----

To unbind a key (either a key which has been bound before, or a default binding):

[source,python]
----
config.unbind(',v', mode='normal')
----

Key chains starting with a comma are ideal for custom bindings, as the comma key
will never be used in a default keybinding.

To suppress loading of any default keybindings, you can set
`c.bindings.default = {}`.

Prevent loading `autoconfig.yml`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want all customization done via `:set`, `:bind` and `:unbind` to be
temporary, you can suppress loading `autoconfig.yml` in your `config.py` by
doing:

.config.py:
[source,python]
----
config.load_autoconfig = False
----

Handling errors
~~~~~~~~~~~~~~~

If there are errors in your `config.py`, qutebrowser will try to apply as much
of it as possible, and show an error dialog before starting.

qutebrowser tries to display errors which are easy to understand even for people
who are not used to writing Python. If you see a config error which you find
confusing or you think qutebrowser could handle better, please
https://github.com/qutebrowser/qutebrowser/issues[open an issue]!