Help & troubleshooting

Homebrew is not installed, or your shell does not know where it lives. The Homebrew page walks through both — the second one catches most people, because Homebrew installs fine and then the PATH lines get skipped.

Because this tap is not one of Homebrew's official ones. A cask is executable Ruby, not a config file, so Homebrew refuses to load one from a third-party source until you explicitly say you trust it. That is a good default and it is protecting you, not annoying you. Read the cask first — it is about 50 lines, mostly a URL and a checksum.

You downloaded a redirect page instead of the disk image. GitLab treats an absolute asset URL as external and answers the release permalink with an interstitial. Use the download button on the install page, which points at the package registry directly, or let Homebrew fetch it.

It should not — the build is signed and notarised. If you see that, treat the copy you have as suspect rather than forcing it open: download it again from the install page or install it with Homebrew, which verifies the checksum for you.

No. The virtual gamepad is built on CoreHID, which Apple introduced in macOS 15 (Sequoia). On anything older the app cannot publish a controller at all, so there is nothing to fall back to.

With Homebrew, along with everything else:

Installed from the disk image? Download the current one and drag it over the old app — Finder will offer to replace it.

The list only shows apps that have asked. Quit GamepadBridge from the menu bar, plug the adapter in, and launch the app again from Applications — the request happens when it first tries to open the device. Launching it from a terminal will not put it in that list, because macOS then attributes the request to the terminal.

Switch that entry off, quit the terminal completely (⌘Q, not just the window), quit GamepadBridge from the menu bar, then double-click the app in Applications. macOS asks again, and this time the request comes from the app itself.

Yes, and you should say yes. The adapter needs about 200 KB of firmware that belongs to Microsoft and cannot legally ship inside the app. GamepadBridge downloads it from Microsoft, verifies it against a known checksum and stores it in ~/Library/Application Support/GamepadBridge/. It happens once, and it is the only network request the app ever makes.

Press the button on the adapter first, then the pairing button on the controller — within a few seconds of each other. If it still will not catch, try a different USB port: some USB-3 ports misbehave with this adapter, and putting a plain USB-2 hub in between fixes it surprisingly often. Also make sure only one copy of GamepadBridge is running.

Something else is holding the adapter. Unplug it, plug it back in, and check that a second instance of the app is not already running. You should never need sudo — on macOS the adapter is claimable as a normal user, so running anything as root here fixes nothing and is not the answer.

No, and you would not want it to. Newer controllers (model 1708 and up) pair with macOS over Bluetooth on their own — nothing needed. This app exists for the adapter, and for the older controllers that only speak to it.

The same ones xow supports: 1537, 1697, 1698 (Elite), 1708 and 1797 (Elite 2). Model 1537 is the one that has been tested end to end on real hardware here. See the compatibility list for adapters and their USB IDs.

First check System Settings → Game Controllers. If the pad shows up there, macOS is happy and the problem is inside the game — many need a restart before they scan for controllers again, and some only look once at launch. If it does not show up there either, go back to Input Monitoring above.

That one is genuinely not mapped. The controller profile macOS recognises does not carry it in its report, and the alternative route the descriptor offers never reaches GameController.framework. Rather than report it as some other button and surprise you mid-game, it is left unmapped. Every other input — face buttons, bumpers, View and Menu, both stick clicks, the d-pad, both sticks and both analog triggers — works.

Possible, and worth knowing in advance: Apple does not guarantee that presenting a virtual controller this way keeps working across releases. If an update breaks it, please open an issue with your macOS version — that is the fastest way to a fix.

It talks to the adapter over USB in userspace, and publishes one virtual gamepad. It installs no kernel extension, adds no login item you did not ask for, and never runs as root. Every line of it is open to read, under GPL-2.0-or-later.

Once, on first launch, to Microsoft — for the adapter firmware described above. Never to us. There is no telemetry, no update ping and no account.

macOS classes talking to an input device as monitoring input, whether or not you are typing on it. It is the same permission a keyboard remapper needs. Without it the device simply never opens — and, unhelpfully, with no error anywhere in the system log.