Skip to content

Getting Started

Jump to bottom
xsyetopz edited this page Oct 15, 2026 · 4 revisions

Getting Started

Learn what OpenJoystickDriver is, install it, and use your first controller.

Note: This page applies to OpenJoystickDriver 0.6.0-alpha.1 and later. Version 0.5.0-beta.4 and earlier do not have all of the features on this page.

Contents

About OpenJoystickDriver

OpenJoystickDriver (OJD) is a macOS menu-bar app that reads game controllers and shows them to macOS games as a standard controller.

How It Works

OJD is one bundle, /Applications/OpenJoystickDriver.app, with no helper app. It runs in your user session. It reads reports from a physical controller over USB, Bluetooth, or a 2.4 GHz dongle. It then publishes a virtual controller that games and apps can read.

The virtual controller uses one of two profiles. One profile is an Xbox Wireless Controller. The other profile is a generic gamepad. OJD selects one automatically. For more information, see How games see your controller.

OJD can also remap controls. A profile can send controller input as keyboard, pointer, or scroll events. For more information, see About profiles.

What OJD Does Not Need

  • OJD does not install a kernel extension.
  • OJD does not need you to turn off System Integrity Protection (SIP).
  • OJD does not need you to turn off Apple Mobile File Integrity (AMFI).

OJD has one driver extension. Its Xbox USB part serves Xbox One and Xbox Series controllers on USB. Other controllers do not use that part. For more information, see Xbox USB driver extension.

What OJD Is Not

  • OJD is not a guarantee that every game reads the virtual controller. Some apps that use SDL may not read it. For more information, see Game and app compatibility.
  • OJD is beta software. Some controllers are not tested on real hardware. For more information, see Supported controllers.

Installing OpenJoystickDriver

Install OpenJoystickDriver in the Applications folder, start it, and check the login item.

Requirements

  • macOS 12 (Monterey) or later.
  • A Mac with Apple silicon or an Intel processor. The app contains both.
  • A controller. For more information, see Supported controllers.

Install the App

  1. Open the OpenJoystickDriver disk image (.dmg).
  2. Drag OpenJoystickDriver.app onto the Applications shortcut in the same window.
  3. Eject the disk image.
  4. Open OpenJoystickDriver from the Applications folder.

Release builds use the name OpenJoystickDriver-VERSION-macOS.dmg. Tester builds also contain the file OpenJoystickDriver-TESTER-BUILD.txt that lists the build details.

Note

Keep the app in /Applications. The commands that manage the login item and the system extension refuse to run from any other location.

First Start

OJD is a menu-bar app. It has no Dock icon. After it starts, a controller icon appears in the menu bar. Click the icon to open the status menu.

At start, OJD also does these actions:

  • On macOS 13 and later, it registers itself as a login item. To turn this off, run the ojd setting set launchAtLogin false command. Turning off Start at login in Settings, or running that command, also records that you opted out, so OJD does not register itself again at the next start. If you change the login item in System Settings instead, OJD reads the change from macOS but does not record an opt-out. For more information, see Console and settings.
  • It checks the OJD driver extension. If the extension needs activation, OJD submits one request. macOS may then ask for your approval.

OJD asks for no privacy permission at start. You grant permissions later. For more information, see Permissions.

Approve the Login Item

If macOS asks, allow OJD in System Settings > General > Login Items. Below macOS 13, OJD cannot register a login item. Open the app yourself after you sign in.

Quickstart

Use your first controller with OpenJoystickDriver in five steps.

Before You Begin

Install the app first. For more information, see Installing OpenJoystickDriver.

Steps

  1. Install and open OpenJoystickDriver from the Applications folder.
  2. Grant access.
    1. Click the controller icon in the menu bar.
    2. If the menu shows Request Access..., click it. Allow OpenJoystickDriver in the Input Monitoring and Accessibility lists.
    3. Open the app window. On the Overview pane, click Restart OpenJoystickDriver if it appears.
  3. Connect your controller with USB, Bluetooth, or a 2.4 GHz dongle.
  4. Check the controller.
    1. Open the Controllers pane.
    2. Select your controller.
    3. Click Open Input Test....
    4. Press buttons and move sticks. The Live input group shows each control.
  5. Play a game. The game reads the virtual controller that OJD publishes.

If step 4 shows no input, see Controller not detected. If the game shows no input, see Game does not see the controller.

Further Reading

OpenJoystickDriver on GitHub · Contributing · Report a bug

Clone this wiki locally