Installing qutebrowser ====================== toc::[] Official vs. community-maintained --------------------------------- Only the following releases are done by qutebrowser's maintainer directly: - Source packages in https://github.com/qutebrowser/qutebrowser/releases[this GitHub repository] and on https://pypi.org/project/qutebrowser/#files[PyPI] - Windows and macOS prebuilt binaries in the GitHub Releases - The `qutebrowser-git` package in the https://aur.archlinux.org/packages/qutebrowser-git/[Archlinux AUR] - Installing <> from the git repository. All other packaging is done by the community, so in case of outdated/broken packages, you will need to reach out to the respective maintainers. Note that some distributions (notably, Debian Stable and Ubuntu) do only update qutebrowser and the underlying QtWebEngine when there's a new release of the distribution, typically once all couple of months to years. [[debian]] On Debian / Ubuntu / Linux Mint / ... ------------------------------------- With those distributions, qutebrowser is in the official repositories, and you can install it with `apt install qutebrowser`. However, when using a stable variant (e.g. Debian Stable / Ubuntu LTS / Linux Mint), note that your versions of qutebrowser and the underlying QtWebEngine will only be updated when there's a new release of your distribution (e.g. upgrading from Ubuntu 22.04 to 24.04): - Ubuntu 20.04, Linux Mint 20: qutebrowser 1.10.1, QtWebEngine 5.12.8 (based on Chromium 69 from 2018) - Ubuntu 22.04, Linux Mint 21: qutebrowser 2.5.0, QtWebEngine 5.15.9 (based on Chromium 87 from 2020) - Debian Bookworm: qutebrowser 2.5.3, QtWebEngine 5.15.13 (based on Chromium 87 from 2020) The old versions of the underlying Chromium will lead to various compatibility issues. Additionally, QtWebEngine on all Debian-based distributions is https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html#browser-security[not covered] by Debian's security support. It's recommended to <> with a newer PyQt/Qt binary instead. If you need proprietary codec support or use an architecture not supported by Qt binaries, starting with Ubuntu 22.04 and Debian Bookworm, it's possible to install Qt 6 via apt. By using `mkvenv.py` with `--pyqt-type link` you get a newer qutebrowser running with: - Ubuntu 22.04, Linux Mint 21: QtWebEngine 6.2.4 (based on Chromium 90 from mid-2021) - Debian Bookworm: QtWebEngine 6.4.2 (based on Chromium 102 from mid-2022) Note you'll need some basic libraries to use the virtualenv-installed PyQt: ---- # apt install --no-install-recommends git ca-certificates python3 python3-venv libgl1 libxkbcommon-x11-0 libegl1-mesa libfontconfig1 libglib2.0-0 libdbus-1-3 libxcb-cursor0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libnss3 libxcomposite1 libxdamage1 libxrender1 libxrandr2 libxtst6 libxi6 libasound2 ---- Additional hints ~~~~~~~~~~~~~~~~ - On Ubuntu 20.04 / Linux Mint 20 / Debian Bullseye, no OpenSSL 3 is available. However, Qt 6.5 https://www.qt.io/blog/moving-to-openssl-3-in-binary-builds-starting-from-qt-6.5-beta-2[moved to OpenSSL 3] for its binary builds. Thus, you will either need to live with `:adblock-update` and `:download` being broken, or use `--pyqt-version 6.4` for the `mkvenv.py` script to get an older Qt. - If running from git, run the following to generate the documentation for the `:help` command (the `mkvenv.py` script used with a virtualenv install already does this for you): + ---- $ pip install -r misc/requirements/requirements-docs.txt # or install asciidoc manually $ python3 scripts/asciidoc2html.py ---- - If you prefer using QtWebKit, there's QtWebKit 5.212 available in those distributions. Note however that it is based on an upstream WebKit from September 2016 with known security issues and no sandboxing or process isolation. - If video or sound don't work with QtWebKit, try installing the gstreamer plugins: + ---- # apt install gstreamer1.0-plugins-{bad,base,good,ugly} ---- + Note those are only needed with QtWebKit, not with the (default) QtWebEngine backend. On Fedora --------- qutebrowser is available in the official repositories: ----- # dnf install qutebrowser ----- Additional hints ~~~~~~~~~~~~~~~~ Fedora only ships free software in the repositories. To be able to play videos with proprietary codecs with QtWebEngine, you will need to install an additional package from the RPM Fusion Free repository. For more information see https://rpmfusion.org/Configuration. ----- # dnf install qt5-qtwebengine-freeworld ----- It's currently unknown what the Qt 6 equivalent of this is. On Archlinux ------------ qutebrowser is available in the official [community] repository. ---- # pacman -S qutebrowser ---- There is also a -git version available in the AUR: https://aur.archlinux.org/packages/qutebrowser-git/[qutebrowser-git]. You can install it using `makepkg` like this: ---- $ git clone https://aur.archlinux.org/qutebrowser-git.git $ cd qutebrowser-git $ makepkg -si $ cd .. $ rm -r qutebrowser-git ---- or you could use an AUR helper like https://github.com/Jguer/yay/[yay], e.g. `yay -S qutebrowser-git`. If video or sound don't work with QtWebKit, try installing the gstreamer plugins: ---- # pacman -S gst-plugins-{base,good,bad,ugly} gst-libav ---- On Gentoo --------- qutebrowser is available in the main repository and can be installed with: ---- # emerge -av qutebrowser ---- If video or sound don't work with QtWebKit, try installing the gstreamer plugins: ---- # emerge -av gst-plugins-{base,good,bad,ugly,libav} ---- To be able to play videos with proprietary codecs with QtWebEngine, you will need to turn off the `bindist` flag for `dev-qt/qtwebengine`. See the https://wiki.gentoo.org/wiki/Qutebrowser#USE_flags[Gentoo Wiki] for more information. On Void Linux ------------- qutebrowser is available in the official repositories and can be installed with: ---- # xbps-install qutebrowser ---- On NixOS -------- Nixpkgs collection contains `pkgs.qutebrowser` since June 2015. You can install it with: ---- $ nix-env -i qutebrowser ---- On openSUSE ----------- There are prebuilt RPMs available at https://software.opensuse.org/download.html?project=network&package=qutebrowser[OBS]. On Slackware ------------ qutebrowser is available in the 3rd party repository at https://slackbuilds.org[slackbuilds.org] An easy way to install it is with sbopkg (frontend for slackbuilds.org) available at https://sbopkg.org[sbopkg.org] sbopkg can be run with a dialog screen interface, or via command line options. After installing the latest sbopkg package, choose your release version, and sync the repo. ---- sbopkg -V 14.2 sbopkg -r ---- Generate a queue file for qutebrowser and dependencies: ---- sqg -p qutebrowser ---- Then load the queue in the dialog queue menu or via: ---- PYTHON3=yes sbopkg -i qutebrowser ---- If you use the dialog screen you can deselect any already-installed packages that you don't need/want to rebuild before starting the build process. Via Flatpak ----------- qutebrowser is available https://flathub.org/apps/details/org.qutebrowser.qutebrowser[on Flathub] as `org.qutebrowser.qutebrowser`. See the https://github.com/flathub/org.qutebrowser.qutebrowser/wiki[qutebrowser Flatpak documentation] for more information about setting up certain features with the Flatpak sandbox. On FreeBSD ---------- qutebrowser is in https://www.freshports.org/www/qutebrowser/[FreeBSD ports]. It can be installed with: ---- # cd /usr/ports/www/qutebrowser # make install clean ---- At present, precompiled packages are not available for this port, and QtWebEngine backend is also not available. On Windows ---------- NOTE: As an additional resource, see https://www.ii.com/installing-qutebrowser-on-windows/[Infinite Ink: Installing qutebrowser on Windows]. There are different ways to install qutebrowser on Windows: Prebuilt binaries ~~~~~~~~~~~~~~~~~ Prebuilt standalone packages and installers https://github.com/qutebrowser/qutebrowser/releases[are built] for every release. Note that you'll need to upgrade to new versions manually (subscribe to the https://listi.jpberlin.de/mailman/listinfo/qutebrowser-announce[qutebrowser-announce mailinglist] to get notified on new releases). You can install a newer version without uninstalling the older one. The binary release ships with a QtWebEngine built without proprietary codec support. To get support for e.g. h264/mp4 videos, you'll need to build QtWebEngine from source yourself with support for that enabled. Nightly builds ~~~~~~~~~~~~~~ If you want to test out new features before an official qutebrowser release, automated https://github.com/qutebrowser/qutebrowser/actions/workflows/nightly.yml[nightly builds] are available. To download them, open the latest run (usually the first one), then download the archive at the bottom of the page. Those builds also include variants with debug logging enabled, which can be useful to track down issues. NOTE: Due to GitHub limitations, you need to be signed in with a GitHub account to download the files. Package managers ~~~~~~~~~~~~~~~~ * PackageManagement PowerShell module ---- PS C:\> Install-Package qutebrowser ---- * https://chocolatey.org/packages/qutebrowser[Chocolatey package] with `choco`: ---- C:\> choco install qutebrowser ---- * Scoop's client ---- C:\> scoop bucket add extras C:\> scoop install qutebrowser ---- Manual install ~~~~~~~~~~~~~~ Use the installer from https://www.python.org/downloads[python.org] to get Python 3 (be sure to install pip). Then <>. On macOS -------- Prebuilt binary ~~~~~~~~~~~~~~~ The easiest way to install qutebrowser on macOS is to use the prebuilt `.app` files from the https://github.com/qutebrowser/qutebrowser/releases[release page]. Note that you'll need to upgrade to new versions manually (subscribe to the https://listi.jpberlin.de/mailman/listinfo/qutebrowser-announce[qutebrowser-announce mailinglist] to get notified on new releases). The binary release ships with a QtWebEngine built without proprietary codec support. To get support for e.g. h264/mp4 videos, you'll need to build QtWebEngine from source yourself with support for that enabled. NOTE: Currently, qutebrowser https://github.com/qutebrowser/qutebrowser/issues/5020[does not use] macOS' https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution[Notarization], due to https://github.com/pyinstaller/pyinstaller/issues/6612[PyInstaller issues] (as well as the requirement to https://developer.apple.com/support/compare-memberships/[pay USD 100 per year to Apple]). Depending on your system settings, this might lead to errors such as "qutebrowser.app can't be opened because Apple cannot check it for malicious software." or "can't be opened because it is from an unidentified developer". You should be able to open the .app by right-clicking it and selecting "Open", see the https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac[macOS documentation] for details. This binary is also available through the https://brew.sh/[Homebrew] package manager as a https://github.com/Homebrew/homebrew-cask[cask]: ---- $ brew install qutebrowser ---- Nightly builds ~~~~~~~~~~~~~~ If you want to test out new features before an official qutebrowser release, automated https://github.com/qutebrowser/qutebrowser/actions/workflows/nightly.yml[nightly builds] are available. To download them, open the latest run (usually the first one), then download the archive at the bottom of the page. Those builds also include variants with debug logging enabled, which can be useful to track down issues. NOTE: Due to GitHub limitations, you need to be signed in with a GitHub account to download the files. Manual Install ~~~~~~~~~~~~~~ Alternatively, you can install the dependencies via a package manager (like https://brew.sh/[Homebrew] or https://www.macports.org/[MacPorts]) and run qutebrowser from source. ==== Homebrew ---- $ brew install pyqt@6 $ pip3 install qutebrowser ---- Packagers --------- qutebrowser ships with a https://github.com/qutebrowser/qutebrowser/blob/main/misc/Makefile[Makefile] intended for packagers. This installs system-wide files in a proper locations, so it should be preferred to the usual `setup.py install` or `pip install` invocation. // The tox anchor is so that old links remain compatible. // When switching to Sphinx, that should be changed. [[tox]] Installing qutebrowser with virtualenv -------------------------------------- IMPORTANT: Before January 2020, this section used to be about installing qutebrowser via `tox` which is a wrapper around `virtualenv`. Now, a dedicated script is used instead. A https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments[virtual environment] (virtualenv, venv) allows Python packages to be installed in an isolated location for a particular application, rather than being installed globally. The `scripts/mkvenv.py` script in this repository can be used to create a virtualenv for qutebrowser and install it (including all dependencies) there. The next couple of sections will explain the most common use-cases - run `mkvenv.py` with `--help` to see all available options. Getting the repository ~~~~~~~~~~~~~~~~~~~~~~ First of all, clone the repository using https://git-scm.org/[git] and switch into the repository folder: ---- $ git clone https://github.com/qutebrowser/qutebrowser.git $ cd qutebrowser ---- Installing dependencies (including Qt) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using a Qt installed via virtualenv needs a couple of system-wide libraries. See the <> for details about which libraries are required. Then run the install script: ---- $ python3 scripts/mkvenv.py ---- This installs all needed Python dependencies in a `.venv` subfolder (which subdirectory the environment is created in is configurable via the `--venv-dir` flag). This comes with an up-to-date Qt/PyQt including a pre-compiled QtWebEngine binary, but has a few caveats: - Make sure your `python3` is Python 3.8 or newer, otherwise you'll get a "No matching distribution found" error and/or qutebrowser will not run. - It only works on 64-bit x86 systems, with other architectures you'll get the same error. - It comes with a QtWebEngine compiled without proprietary codec support (such as h.264). See the next section for an alternative install method which might help with those issues but result in an older Qt version. You can specify a Qt/PyQt version with the `--pyqt-version` flag, see `mkvenv.py --help` for a list of available versions. By default, the latest version which plays well with qutebrowser is used. NOTE: If the Qt smoke test fails with a _"This application failed to start because no Qt platform plugin could be initialized."_ message, most likely a system-wide library is missing. Pay attention to a _QLibraryPrivate::loadPlugin failed on ..._ line for details. Installing dependencies (system-wide Qt) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Alternatively, you can use `mkvenv.py --pyqt-type link` to symlink your local PyQt/Qt install instead of installing PyQt in the virtualenv. However, unless you have a new QtWebKit or QtWebEngine available, qutebrowser will not work. It also typically means you'll be using an older release of QtWebEngine. On Windows, run `set PYTHON=C:\path\to\python.exe` (CMD) or `$Env:PYTHON = "..."` (Powershell) first. There is a third mode, `mkvenv.py --pyqt-type source` which uses a system-wide Qt but builds PyQt from source. In most scenarios, this shouldn't be needed. Creating a wrapper script ~~~~~~~~~~~~~~~~~~~~~~~~~ Running `mkvenv.py` does not install a system-wide `qutebrowser` script. You can launch qutebrowser by doing: ---- .venv/bin/python3 -m qutebrowser ---- You can create a simple wrapper script to start qutebrowser somewhere in your `$PATH` (e.g. `/usr/local/bin/qutebrowser` or `~/bin/qutebrowser`): ---- #!/bin/bash ~/path/to/qutebrowser/.venv/bin/python3 -m qutebrowser "$@" ---- Updating ~~~~~~~~ If you cloned the git repository, run `mkvenv.py --update` which will take care of updating the code (via `git pull`) and recreating the environment with the newest dependencies. Alternatively, you can update your local copy of the code (e.g. by pulling the git repo, or extracting a new version) and the virtualenv should automatically use the updated versions. However, dependencies won't be updated that way.