A userscript to view Gemini pages in qutebrowser
67d8f98f — Sotiris Papatheodorou 2 years ago
Bump version to 1.0.0
a49fba2a — Sotiris Papatheodorou 2 years ago
Mention possible CSS styles
940b0341 — Sotiris Papatheodorou 2 years ago
Update limitations



You can also use your local clone with git send-email.


A qutebrowser userscript that allows viewing Gemini pages by pressing a custom key. The pages are converted to HTML by the script and then displayed in qutebrowser.

The script borrows code from gcat, many thanks to its authors!


The XDG Base Directory Specification is supported but the default directory paths are used for simplicity.

  1. Copy qute-gemini and qute-gemini-tab into ~/.local/share/qutebrowser/userscripts/.

  2. Set custom keybindings for opening Gemini URLs by adding the following lines to ~/.config/qutebrowser/config.py:

    # Open in the current tab
    config.bind(';g', 'hint links userscript qute-gemini')
    # Open in a new tab
    config.bind(';G', 'hint links userscript qute-gemini-tab')

    The script only processes gemini:// URLs and opens all other URLs using qutebrowser, so opening a non-gemini:// should also work.

  3. Re-source the qutebrowser config by running config-source or restart qutebrowser and visit the Gemini spec homepage to ensure that everything works.

#Custom CSS

You can create a CSS file ~/.local/share/qutebrowser/userscripts/qute-gemini.css and qute-gemini will use it to style Gemini pages shown in qutebrowser. The kineto or Gemini homepage CSS styles both work well.

#Known issues

  • Userscript limitations
    • Only text/gemini content is shown. Any other MIME types received over Gemini are considered an error.
    • There is no support for user input (Gemini codes 1*).
    • There is no support for client certificates (Gemini codes 6*).
    • Opening non-gemini:// URLs with the userscript might not work correctly in rare cases.
  • Qutebrowser limitations
    • Opening gemini:// URLs from the URL bar does not work. It is only possible to open URL in the current page via the hints.
    • Opening gemini:// URLs by clicking on them does not work, only opening them via the keybinding is possible.
    • Qutebrowser userscripts don't accept arguments. My solution to being able to open links in the same or a different tab was to call the script under a different name.


Copyright 2019 Solderpunk, 2020 Aaron Janse, 2020 petedussin, 2020-2021 Sotiris Papatheodorou

This program is Free Software: You can use, study share and improve it at your will. Specifically you can redistribute and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

gcat is distributed under the BSD 2-Clause license.