Basic PAYE Tools — Linux installation help
Updated 1 June 2022
© Crown copyright 2022
This publication is licensed under the terms of the Open Government Licence v3.0 except where otherwise stated. To view this licence, visit nationalarchives.gov.uk/doc/open-government-licence/version/3 or write to the Information Policy Team, The National Archives, Kew, London TW9 4DU, or email: psi@nationalarchives.gov.uk.
Where we have identified any third party copyright information you will need to obtain permission from the copyright holders concerned.
This publication is available at https://www.gov.uk/government/publications/getting-basic-paye-tools-working-on-linux/getting-basic-paye-tools-working-on-linux
This guide applies to Basic Pay As You Earn (PAYE) Tools (BPT) version 22.0 onwards.
Basic dependencies
Basic PAYE Tools is a 64-bit application which is designed to run in a graphical desktop environment. It has been tested on the following distributions:
- Ubuntu 20.04 LTS
- Ubuntu 21.10 (the most recent version available during development)
In order to run, BPT depends on glibc >= 2.28
Running the installer
The installer 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.
If nothing happens when you run the installer by double-clicking the program, you may be able to diagnose some problems by running it in text mode from the command line.
Run the installer in text mode using the following command (replacing “./payetools-rti-xx.y.zzzzz.aaa-linux” with the filename of the installer you downloaded):
$ ./payetools-rti-xx.y.zzzzz.aaa-linux –mode text
If you see an error message like the following one when running the installer, then your Linux installation does not meet the requirements to run 64-bit applications and you will not be able to install Basic PAYE Tools.
./payetools-rti-xx.y.zzzzz.aaa-linux:
cannot execute binary file: Exec format error
Running the Basic PAYE Tools application
By default Basic PAYE Tools will install below your home folder, for example.
${HOME}/HMRC/payetools-rti
The installer also attempts to provide a desktop icon and add Basic PAYE Tools to the desktop environment’s usual menu or launcher.
The first time you run Basic PAYE Tools from the desktop shortcut, you may need to right-click on it and select “Allow Launching”. Alternatively on other desktop environments you may be prompted to “Trust and launch” the application.
If nothing happens after this, you can again diagnose problems via the command line. Check the console output from running:
$ ~/HMRC/payetools-rti/rti.linux
A log file is also created at /tmp/rti.log.
The console output and log file will contain details which may help you to resolve the issue yourself, for example, missing dependencies. However if you require help have the log file (and any other log files in /tmp named rti*) ready when you contact HMRC.
Note: there is a known issue in Ubuntu 20.04 which prevents rti.linux from launching when double-clicking the file directly in the file explorer.
See https://bugs.launchpad.net/ubuntu/+source/file/+bug/1747711 .
This results in the message:
Could Not Display “rti.linux”
There is no application installed for “shared library” files
If you encounter this message, use the desktop shortcut, menu/Dash shortcut or the console command to launch Basic PAYE Tools.
Assistive Mode Server
If you choose to run Basic PAYE Tools with Assistive Software support enabled, BPT will run in the background as a server, and attempt to spawn its interface in your desktop environment’s default web browser.
The server will remain running in the background. Most desktop environments will display a system tray icon with the HMRC logo which allows the server to be exited gracefully. However, some environments, such as Ubuntu Unity, do not display the system tray icon. An alternative method of exiting the server cleanly is to visit the following URL:
http://127.0.0.1:46729/QUIT