• Ubuntu
• Web development

Debugging iOS Safari from Linux

While implementing Apple Pay on the Bixoto checkout, a collegue of mine was struggling with strange errors on iOS, but couldn’t properly debug it from their Linux computer. Thankfully, it’s possible to get the debugger to work on Linux, although the experience is not exactly smooth.

The commands used in this guide are for Ubuntu with Homebrew on Linux. You should be able to follow the guide with other distros, but the commands won’t be the same.

First, we need install usbmuxd. This one is easy:

sudo apt install usbmuxd
sudo service usbmuxd start

Then, install ios-webkit-debug-proxy. This one is not available in apt, so either you build it from source (but it requires to first build and install some dependencies), either you install it with Homebrew:

brew install ios-webkit-debug-proxy

Try now to plug your device. If asked to trust the computer, say Yes and enter your code.

Run idevice_id. If you don’t see your device, you can check:

sudo systemctl status usbmuxd

But usually you can fix this by unplugging and re-plugging your device. Once it works, you should see your device’s serial number:

$> idevice_id
<serial number> (USB)

Now install ios-safari-remote-debug. It’s easier to install and use than ios-safari-remote-debug-kit, but it requires Go for the build:

# Clone the repo
git clone --depth=1 https://git.gay/besties/ios-safari-remote-debug/
cd ios-safari-remote-debug
# Build
go build
./ios-safari-remote-debug build -t releases/Apple/Safari-17.5-macOS-14.5

Then run it:

./ios-safari-remote-debug serve

It should print something like this:

2026/01/13 10:40:59 Listening on :8924

In another shell, start ios_webkit_debug_proxy that you installed before with Homebrew:

$> ios_webkit_debug_proxy

It should print something like:

Listing devices on :9221
Connected :9222 to <your device name> (<your device serial number>)

Now you’re done with the shell part.

Open http://127.0.0.1:8924/ in Chrome. The page should load, but fail to work correctly because it tries to connect to http://127.0.0.1:9222 client-side, causing CORS errors. Install this extension and enable it on the page. Reload it. You should now see your device listed, with below a list of tabs open in Safari (yes, the page is hard to read because it’s written in black on dark grey).

Now, on your device, browse to the page you want to debug in Safari. Refresh the debugger page: you should see the tab’s title under your device name. Click on it. If everything works well, you should now see the debugger!

Even if at this point it works, note that sometimes the debugger crashes and needs to be reloaded (just refresh the page). Also, the button to clear the console doesn’t seem to work: you need to type clear() in the console.

This guide was made possible by Jade’s blogpost about it, although since 2023 some of the tools she hints at have now been replaced.