pvsr.dev
1# qutebrowser profile manager
2
3[](https://builds.sr.ht/~pvsr/qbpm/commits/main?)
4[](https://pypi.python.org/pypi/qbpm)
5
6qbpm (qutebrowser profile manager) is a tool for creating, managing, and running
7[qutebrowser](https://github.com/qutebrowser/qutebrowser) profiles. Profile support
8isn't built in to qutebrowser, at least not directly, but it does have a `--basedir` flag
9which allows qutebrowser to use any directory as the location of its config and
10data and effectively act as a profile. qbpm creates profiles that source your
11main qutebrowser `config.py`, but have their own separate `autoconfig.yml`, bookmarks, cookies,
12history, and other data. Profiles can be run by starting qutebrowser with the
13appropriate `--basedir`, or more conveniently using the `qbpm launch` and `qbpm choose` commands.
14
15qutebrowser shares session depending on the basedir, so launching the same
16profile twice will result in two windows sharing a session, which means running
17`:quit` in one will exit both and launching the profile again will reopen both
18windows. But launching two distinct profiles will start two entirely separate
19instances of qutebrowser which can be opened and closed independently.
20
21## Usage
22To create a new profile called "python" and launch it with the python docs open:
23```
24$ qbpm new python
25$ qbpm launch python docs.python.org
26```
27
28Note that all arguments after `qbpm launch PROFILE` are passed to qutebrowser,
29so options can be passed too: `qbpm launch python --target window pypi.org`.
30
31If you have multiple profiles you can use `qbpm choose` to bring up a list of
32profiles and select one to launch. Depending on what your system has available
33the menu may be `dmenu`, `fuzzel`, `fzf`, an applescript dialog, or one of many
34other menu programs qbpm can detect. Any dmenu-compatible menu can be used with
35`--menu`, e.g. `qbpm choose --menu 'fuzzel --dmenu'`. As with `qbpm launch`,
36extra arguments are passed to qutebrowser.
37
38Run `qbpm --help` to see other available commands.
39
40By default when you create a new profile a `.desktop` file is created that
41launches the profile. This launcher does not depend on qbpm at all, so if you
42want you can run `qbpm new` once and keep using the profile without needing
43qbpm installed on your system.
44
45## Installation
46If you use Nix, you can install or run qbpm as a [Nix flake](https://nixos.wiki/wiki/Flakes).
47For example, to run qbpm without installing it you can use `nix run github:pvsr/qbpm -- new my-profile`.
48
49On Arch and derivatives, you can install the AUR package: [qbpm-git](https://aur.archlinux.org/packages/qbpm-git).
50
51Otherwise you can install directly from PyPI using [uv](https://docs.astral.sh/uv/guides/tools/),
52pip, or your preferred client. With uv it's `uv tool run qbpm` to run qbpm
53without installing and `uv tool install qbpm` to install to `~/.local/bin`.
54The downside of going through PyPI is that the [man page](https://github.com/pvsr/qbpm/blob/main/qbpm.1.scd)
55and shell completions will not be installed automatically.
56
57On Linux you can copy [`contrib/qbpm.desktop`](https://raw.githubusercontent.com/pvsr/qbpm/main/contrib/qbpm.desktop)
58to `~/.local/share/applications` to create a qbpm desktop application that runs
59`qbpm choose`.
60
61### MacOS
62
63Nix and uv will install qbpm as a command-line application, but if you want a
64native Mac application you can download [`contrib/qbpm.platypus`](https://raw.githubusercontent.com/pvsr/qbpm/main/contrib/qbpm.platypus),
65install [platypus](https://sveinbjorn.org/platypus), and create a qbpm app with
66`platypus -P qbpm.platypus /Applications/qbpm.app`. That will also make qbpm
67available as a default browser in `System Preferences > General > Default web browser`.
68
69Note that there is currently [a qutebrowser bug](https://github.com/qutebrowser/qutebrowser/issues/3719)
70that results in unnecessary `file:///*` tabs being opened.