fixing your desktop

Installing HMRC’s PAYE tools on OS X

The old PAYE tools was bad, really bad – I saw it generate the wrong figures once (i.e. actively costing UK small businesses real money for HMRC’s carelessness).

The new one is great – but it hasn’t been tested properly. The install instructions are wrong, it installs illegally on OS X, and it has a major bug in the configuration system. By accident, I discovered it’s all written in Python, which I find very interesting although currently it’s a bad advert for the language :(.

Here’s how I fixed it…


The app installs itself using Administrator priviledges (this is very wrong. I think the developers made a massive mistake here – it makes your computer WIDE OPEN to viruses).

Using those privs … to add insult to injury, it actually locks you out from editing it, moving it to the correct install location, etc!

(the installer asks where you want to install … and then ignores you and installs somewhere else. Pretty obvious bug, I’m suprised they didn’t notice this one during testing)

Solution 1:

  1. Right click the folder it installed to
  2. Select “Info”
  3. Click the padlock at bottom if its “closed” until it becomes “open” (REQUIRES YOUR ADMIN PASSWORD)
  4. Select the dropdown for “Admin” or for your username and select “Read&Write” (HMRC should not have changed this under any circumstances!)
  5. Repeat those steps for the file “” inside the folder
  6. Repeat those steps for the file “rti.cfg” inside the folder


No app should install to a random folder. To fix this (optional) you can do:

  1. Delete all the crap that HMRC incorrectly creates in your Applications folder. This means “Everything except and rti.cfg”
  2. Drag/drop AND rti.cfg into your Applications folder
  3. NB: unfortunately, because they wrote this (poorly) in Python, the rti.cfg file is necessary AND must live inside your Applications folder. Yuck. Violates basic install rules on OS X, but until HMRC fixes their app … nothing you can do.

Problem 2: Can’t backup any of the data; can’t save it; etc

By default, the app saves all its data into your personal user account, in a sometimes-hidden folder (some OS X installs hide this by default).


In reality, you are insane if you’re not actively storing your company data on a networked drive, a remote backup solution, etc. Hey – even Dropbox, if you like them enough (their security may be good enough for you; some are content with it).

Fortunately, HMRC supports this feature … but their documentation is missing or wrong :(.

In my case: we put all this stuff into a private git repository, where it’s 100% reproducible later.

HMRC’s own instructions for “unbreaking” their software:

  1. “In Windows …”
  2. “…everyone else: Buy Windows…”

(sad face).

Solution 2:

  1. Run the
  2. Create your employer
  3. Quit
  4. Restart … and check the Employer appears at extreme top left of screen in the “top” left-hand-side navbar.
    1. …if NOT: your is FUBAR, and you should re-install it from scratch.
  5. Close the app again
  6. Find the “rti.cfg” file (lives in same folder as the
  7. Open it with TextEdit
  8. Give it the location where you want to store your data (“the database” as HMRC calls it; technically yes: it’s an SQLite database, if you’re interested in that kind of thing)
  9. NB: this DOES NOT WORK the way HMRC has documented it for Windows! I’m guessing it’s broken on all platforms, since it’s written in Python, but I didn’t bother checking a Windows install
    1. Edit the first line in “[General]” and change:
      1. userdatamode=0
      2. … to:
      3. userdatamode=2
    2. Edit the second line in “[General]” and change:
      1. userdatadir=/Users/(your username)/payetools-rti
      2. … to: (THIS IS IMPORTANT)
      3. userdatadir=
      4. …and drag/drop your preferred folder from Finder into TextEdit, dropping after the equals sign.
      5. …net result: it should automatically work out the long and complex location of your folder
      6. NB: a pleasant surprise: it DOES SUPPORT spaces in filenames – no special handling needed. But it will appear to fail because of the other bugs
    3. Save rti.cfg
    4. Run
    5. It should say “no employers found” (because it’s using the new location, and you haven’t moved the file yet)
    6. Quit
    7. Check your folder, see what’s there.
      1. This is where it gets interesting
      2. Whatever folder you chose for the location inside rti.cfg, HMRC creates two subfolders (undocumented): “HMRC/payetools-rti”
      3. …and it dumps the database in there.
      4. So, (making sure you’ve already quit!), move the contents of the old “payetools-rti” folder into the new “payetools-rti” folder
        1. The “old” folder will be in “/Users/(your username)/HMRC” which you can get to in folder by going to your user-folder and findign the HMRC folder.
        2. If your user-folder is hiddin in Finder (by default), you can run finder and do SHIFT + COMMAND + H to automatically go there
      5. Restart
      6. …it should now find your Employer again

2 replies on “Installing HMRC’s PAYE tools on OS X”

As in: “the app is written in some other language, and Python is used to tie together disparate parts”?

Or as in: “you can’t ‘write’ code in Python, you can only ‘make scripts'”?

Comments are closed.