Skip to content

Loading the extension manually

Jump to bottom
Sami Vänttinen edited this page Aug 14, 2023 · 11 revisions

Loading the extension manually

First, download and extract the sources of the current develop branch from GitHub. For git users, it's more obvious to use git clone https://github.com/keepassxreboot/keepassxc-browser.git.

It's recommeneded to temporarily disable the stable extension if that is installed. The temporary extension can give some kind of warning about unexpected property but that can be ignored. It's caused by the manifest.json file that contains browser specific properties for both Firefox and Chromium.

Firefox

  1. Open about:debugging#/runtime/this-firefox and click Load Temporary Add-on.
  2. Browse to the extension's keepassxc-browser/ subfolder and select manifest.json file.

With Firefox you can also load a new Firefox process with the extension using web-ext. See https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/ for further information.

Please note that with Firefox the temporary extension will be unloaded if the browser is closed. The temporary extension must be loaded again after every restart.

Chrome (and other Chromium-based browsers)

  1. Go to chrome://extensions/ and enable Developer mode.
  2. Click Load unpacked button. Select the keepassxc-browser/ subfolder under extracted extension folder.
  3. Check the KeePassXC-Browser ID in the extension card. It should differ from the default when loaded manually from sources.
  4. Modify the native messaging JSON script (instructions below).

Modify the native messaging JSON script for Chromium

Open the org.keepassxc.keepassxc_browser.json (Troubleshooting guide shows the locations) and add the extension debug ID to the json:

    "allowed_origins": [
        "chrome-extension://kdggfocfphncghpalgjiecgcnpgglmef/",
        "chrome-extension://oboonakemofpalcgghocfoadofidjkkk/"
    ],

It's also preferred to disable Update native messaging manifest files option from KeePassXC's Browser Integration Advanced tab. When you reload the extension it should now connect to KeePassXC. Debug builds of KeePassXC already support setting a custom extension ID directly from KeePassXC settings.

Build extension into .zip file and load

This step is only needed for deployment. It loads all the translations from Transifex and adjusts manifest.json separately for Firefox and Chromium-based browsers. For example, it allows to use SVG icons with Firefox.

Prerequisites

  • Run npm install.
  • Install the Transifex CLI tool.
  • Log into Transifex (e.g., with your GitHub account), click "Join team" on this page and, after a page reload, make sure "KeePassXC" is the active organization in the drop-down box on the top of the page.
  • Go to your Transifex user settings, generate an API token, give it a name associating it with KeePassXC and save it in your config file.

Building

Run npm run build. Use npm run build -- --skip-translations to skip downloading or updating any translations.

Installing

This method installs the development version as a permanent extension. Use it only if you really need to, for example testing features with browser restarts.

Firefox

  • Visit about:config and set xpinstall.signatures.required to false. This requires ESR, Developer Edition or Nightly. (Remember to undo this.)
  • Visit about:addons.
  • Go to the custom add-on settings and export a backup.
  • Uninstall the add-on.
  • Click the gear button, "Install Add-on From File..." and choose the built .zip file for Firefox.
  • Restart the browser and connect your database via the settings.

Chromium-based browsers

Use the normal temporary extension loading feature described earlier.

Clone this wiki locally