Guidance

Basic PAYE Tools — Linux installation help

Updated 18 March 2026

This guide applies to Basic Pay As You Earn (PAYE) Tools (BPT) Version 26.0, last updated 16 February 2026.

Basic dependencies

Basic PAYE Tools is a 64-bit AppImage which is designed to run in a graphical desktop environment. It has been tested on the following distributions:

• Ubuntu 24.04 LTS
• Ubuntu 25.10 (the most recent version available during development)

In order to run, BPT depends on 'glibc >=2.31' and 'libfuse2' and 'libopengl0'

You may need to install libfuse2 and libopengl0 on Ubuntu if they are not already present. This can be done with the following commands:

• sudo apt install libfuse2
• sudo apt install libopengl0

New AppImage format

The AppImage bundle can be run directly and there is no separate installation step.

You may be prompted to grant the AppImage executable permissions the first time you run it.

The AppImage should be extracted from the zip download before running it. Some graphical user interface (GUI) tools, for example Ubuntu’s Archive Manager, will allow the AppImage to be run from within their interface without extraction, but it may not run correctly that way.

BPT will store its data in '${HOME}/HMRC/payetools-rti'. If this directory does not exist, it will be created.

The Basic PAYE Tools AppImage does not automatically provide a desktop icon or add itself to the desktop environment’s usual menu or launcher.

You can read more information about the AppImage format and on getting an AppImage to run on your distribution on the AppImage website.

Configuration changes for version 25.0 onwards

Basic PAYE Tools version 25.0 onwards updates several core components. This means some configuration options have changed or moved.

To start Basic PAYE Tools, run the 'Basic_PAYE_Tools-xx.0.xxxxx.yyy-x86_64.AppImage' program.

The updated user interface application has its own configuration file:

# macOS and Linux

${HOME}/HMRC/payetools-rti/bptshell-settings.ini

The log files are now written to:

${HOME}/HMRC/payetools-rti/logs/

Important Notice for Users on BPT 24.x

If uninstalling BPT version 24.1, ensure you back up your user data first. Do not delete your user data when running the uninstall application, as this will remove your database from the filesystem.

Assistive Mode

If you normally use Basic PAYE Tools in Assistive Mode, you will need to add the following lines to bptshell-settings.ini:

[General] mode=assitive

This setting was previously in rti.cfg in the install directory. As of version 25.0 and above, setting this value in rti.cfg will no longer have any effect.

Running the AppImage

The AppImage should be extracted from the zip download before running it. Some GUI tools, for example Ubuntu’s Archive Manager, will allow the installer application to be run from within their interface without extraction, but it may not run correctly that way.

Change directory to the location of the AppImage file extracted from the zip and execute it:

]$ ./Basic\_PAYE\_Tools-xx.0.xxxxx.yyy-x86\_64.AppImage

Troubleshooting the AppImage

If nothing happens when you run the AppImage by double-clicking the program, you may be able to diagnose some problems by running it in text mode from the command line.

A log file is also created at '${HOME}/HMRC/payetools-rti/logs/'. For example: '~/HMRC/payetools-rti/logs/'.

The console output and log file will contain details which may help you to resolve the issue yourself. For example, if there are missing dependencies.

If you need help, you should have the log file ready when you contact HMRC.

Background server process

An alternative method of exiting the server cleanly is to visit the following URL:

http://127.0.0.1:46729/QUIT

This can be useful if you find the background server process still running, or if the AppImage doesn’t cleanly exit.