The UBports Installer turns a phone flash into a guided desktop

A desktop app that wraps the flashing tools

ubports-installer is described as a simple tool to install Ubuntu Touch on UBports devices, and the pitch in the README is that installing a third party operating system has never been so easy. The mechanism underneath is not secret. The tool talks to the device with ADB, Fastboot and Heimdall, the three flashing and communication tools that any manual install of Ubuntu Touch would use, and the value it adds is the orchestration and the guidance. The project is an Electron application written in JavaScript, with the source under src/ and the entry point at src/main.js exposed as a bin command. The package keywords name the whole stack, Ubuntu, Ubuntu Touch, UBports, Android, ADB, Fastboot and Heimdall. The user-facing surface is the on-screen flow: connect a supported device to your PC, follow the instructions, and the tool does the rest. The library list in the documentation shows how much of the heavy lifting is delegated, with promise-android-tools described as an extensive wrapper for ADB, Fastboot and Heimdall, and android-tools-bin providing cross-platform binaries for the same three tools.

Device support comes from a separate config repository

The design decision with the biggest consequences for how you use this tool is that the device knowledge lives outside the installer. By default the Installer always uses the latest version of the installation configuration files, which are hosted in the ubports/installer-configs repository, and the structure of those files is specified in that repository's own readme. The reason for the split is obvious once you look at it. A new phone, or a new revision of a phone, needs new flashing instructions, and those instructions change far more often than the application logic. Keeping them in their own repository means a device can be added or updated without touching the installer code. It also means the installer depends on a remote resource at runtime, which is a real operational consideration for anyone reproducing an install later. If you want to pin behaviour, you can override the official config by loading a YAML local file, and the tool accepts that through the -f option, which the documentation says can be used to test configuration changes or even to add new devices to the installer.

Running it from a terminal as well as a window

Although the tool is a desktop application, it exposes a command line interface, and the development instructions show the help output with all the options. You start it with pnpm start, passing arguments after the separator.

$ pnpm start -- -h

The options are short and practical. There is -f to override the official config by loading a YAML local file, -v for verbose output where multiple -v options increase the verbosity, -d to enable Electron's web debugger so you can inspect the frontend, --systemimage to set a custom system image server URL instead of the default, and -h for help, alongside -V for the version number. That combination is the interesting part. The same binary that drives a guided window can be pointed at a local configuration file, which is what makes it possible to test a configuration change before it goes into the shared repository, and the verbosity flags are what you want when a flash fails halfway.

For development, the setup is a clone, a directory change and an install.

git clone https://github.com/ubports/ubports-installer.git
cd ubports-installer

pnpm install

Node and pnpm both have to be present, and the repository carries a .nvmrc and a .npmrc for that reason.

Packaging targets five platforms and four architectures

The build script is a Node program with its own set of options, and the target matrix is wide.

$ ./build.js --help

You choose the operating system with -o, taking darwin, win32 or linux, the package format with -p, taking deb, snap, AppImage, dmg, portable or dir, and the architecture with -a, taking armv7l, x64, ia32 or arm64, with defaults of linux, dir and x64. The -e option takes extra JSON for the package metadata, and -V prints the version. This is a proper release pipeline rather than a build for your own machine, and the resulting packages are what users actually download, since the README points people at per-platform downloads for Linux as snap, AppImage and deb, for macOS as dmg, and for Windows as exe. The version in the package manifest is 0.11.2, and the recent release history shows 0.11.0, 0.11.1 and 0.11.2 published in June and July 2025, so this is a project on a slow, deliberate release cadence with the last push to the repository on 2026-09-28.

The log file is where the answers are

The troubleshooting section is short and points in two directions, one to documentation and one to a log file. The documentation for installation is in the user guide, and the support channels listed are Telegram, Matrix, the UBports forum and Ask Ubuntu, with a note that if you believe the installer is not working correctly you can file a new issue. The more useful tip is the Report a bug button inside the installer, which generates a template with all the important metadata already filled out, so a report is useful on the first try. The log locations are platform specific and worth knowing before you need them. On Linux it is at ~/.cache/ubports/ubports-installer.log, or under the snap package path if you installed that way, on Windows it is at %APPDATA%\ubports\ubports-installer.log, and on macOS it is under $HOME/Library/Caches/ubports/ubports-installer.log. The installer usually offers to create a bug report when it hits an error, and the documentation is explicit that using that feature is a good idea because the developers will almost always then have the information they need.

Where the installer is the wrong tool

Three limits. The first is that the tool is built around an interactive session with a physical device connected to your machine, which makes it a poor fit for automated or reproducible device fleets, where a script that calls the flashing tools directly with a pinned config would be a better shape. The second is the dependency on the remote config repository, since the default behaviour is always to use the latest version of the installation configuration files, so an install that worked last month can behave differently today without any change on your side, and the -f override exists to manage that risk but has to be used deliberately. The third is the licence, which is GPL-3.0 with original development credited to Marius Gripsgård. For a tool people run on their own machines, the copyleft obligations of the distribution are manageable, but if you were planning to build a commercial product on top of the flashing logic, that is a question for your own legal review. The library set is worth a look in that context, because progressive-downloader, promise-android-tools and android-tools-bin are separate free and open source NPM packages maintained by the same foundation, and the promise-android-tools wrapper in particular is the piece a different product might want to reuse.

Editorial conclusion

Adopt the UBports Installer if you want to put Ubuntu Touch on a supported device and you want the flashing steps handled for you, with a GUI that also runs headless from the command line. Skip it if you need the flashing to be scripted and reproducible in CI, because the tool is built around an interactive session with a connected device, and skip it if your device is not in the config repository. Before your first run, check that your device appears in the installer-configs repository and read the log locations in the documentation, since the log file is where the answer to most failures will be, and remember that the default config is always the latest one fetched from that repository.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. ubports/ubports-installer on GitHub