HM Revenue & Customs

Basic PAYE Tools

Readme help file
----------------

Welcome to Basic PAYE Tools.

Here is a brief guide to help you to run the software, including some useful
information for system administrators. For the latest guidance, please always
visit: https://www.gov.uk/topic/business-tax/paye

Version 26.1, last updated 12/05/2026.


Contents
--------

1. System requirements

2. Configuration changes in version 25

    (a) Starting the program
    (b) Assistive mode
    (c) Welsh language

3. Firewall information

4. Command line options

5. Linux AppImage format

6. Troubleshooting



1. System requirements
----------------------

The following operating systems are supported:

    * Windows 10 (22H2) and 11 (24H2)
    * macOS 15 ("Sequoia") and 16 ("Tahoe")
    * Ubuntu Linux version 24.04 LTS and 25.10.

BPT is built exclusively for x64 (64-bit Intel/AMD compatible) operating systems.
macOS is supported on Apple Silicon–based Mac computers via the Rosetta 2 emulation layer.

Basic PAYE Tools requires DirectX 11 capable hardware.

You can use the following browsers if you need assistive software support:

    * Microsoft Edge (Windows only)
    * Google Chrome
    * Mozilla Firefox
    * Apple Safari (macOS only)

An active internet connection is required for submitting payroll information
online, automatic updates, email features, and web links.

Adobe Reader or a compatible equivalent is required to open printable forms.


2. Configuration changes from version 25.0 onwards
--------------------------------------------------

Basic PAYE Tools version 25.0 introduced updates to several core components
and as a result, some configuration options have changed or moved.

(a) Starting the program
------------------------

To start Basic PAYE Tools, run the "Basic_PAYE_Tools-26.1.26134.173934-x86_64.AppImage" program.

The updated user interface application has its own configuration file:

    # Windows
    %APPDATA%\HMRC\payetools-rti\bptshell-settings.ini

    # macOS and Linux
    ${HOME}/HMRC/payetools-rti/bptshell-settings.ini

The log files are now written to:

    # Windows
    %APPDATA%\HMRC\payetools-rti\logs\

    # macOS and Linux
    ${HOME}/HMRC/payetools-rti/logs/

(b) 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=assistive

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

(c) Welsh language
------------------

If you normally use Basic PAYE Tools in Welsh, you can now change the
language using the System Tray icon.

    - Open Basic PAYE Tools.
    - in the System Tray (usually at the bottom-right of the screen), look for
      the Basic PAYE Tools green crown icon.
      (NOTE: you may have to select the arrow to view all icons in the System Tray).
    - Right click on the crown logo.
    - Select 'Language' and choose the required language.
    - In Basic PAYE Tools, a message will be displayed confirming the change
      will take effect after restarting the application.
    - Close Basic PAYE Tools and reopen.
    - Basic PAYE Tools will now be displayed in the chosen language.



3. Firewall information
-----------------------

In order to allow Basic PAYE Tools to submit payroll information online and
automatically check for updates, you may need to create exception rules in your
firewall to allow the "rti.linux" program to connect to the
internet.

You may also need to create exception rules in your firewall to allow
rti.linux to act as a server.

If your internet connection is through a proxy then you will need to add an
exception for 127.0.0.1:46729. This will be required regardless of
whether you use Basic PAYE Tools in standard or assistive mode.

The port number can be adjusted via bptshell-settings.ini (see above for the
location of this file on your operating system).

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

If you are not sure how to create a firewall rule for your product,
please consult the help documentation provided with the software, or
contact the firewall provider.


4. Command line options
-----------------------

To start Basic PAYE Tools from the command line, you must run
Basic_PAYE_Tools-26.1.26134.173934-x86_64.AppImage in the install directory.

The following command line option is available:

--assistive     use the HTML interface in default web browser (provided for
                full Assistive Software support)


5. Linux AppImage format
------------------------

For Linux, Basic PAYE Tools is now provided as a standalone AppImage
executable. Extract the AppImage to a location of your choice, make it
executable and run it directly. The database and configuration files continue
to be read from the same locations, subject to the changes noted above.

You may need to install the following: libfuse2 and libopengl0.
On Ubuntu systems this is:

	sudo apt install libfuse2
	sudo apt install libopengl0	

For additional help using Basic PAYE Tools on Linux, please visit:

    https://www.gov.uk/government/publications/getting-basic-paye-tools-working-on-linux

For additional built-in options for the AppImage, you can use the additional
command line option:

--appimage-help     show a list of built-in AppImage functions.


6. Troubleshooting
------------------

* Basic PAYE Tools opens but displays a blank page / white screen.

This is known to occur when Basic PAYE Tools is run on old hardware that does
not support DirectX 11.

If your system is affected by this issue, we recommend running Basic PAYE Tools
in assistive mode. You can do this by:

* the Start Menu shortcut,

* the "--assistive" command line option, or

* amending your bptshell-settings.ini file as described in "Configuration
  changes for version 25" (above).
