USB Ports Mapper iconUSB Ports Mapper icon
Utilities

USB Ports Mapper

Build Hackintosh USB port maps live from IOKit with instant Kext & SSDT generation.

Download Free

— downloads

macOS 11.0+ Universal Binary Free
USB Ports Mapper dark screenshot USB Ports Mapper light screenshot

⚠️ Caution & Testing Advice: Please copy your EFI folder to a USB disk first and test the generated files there. Make sure everything is working correctly before replacing your existing kext files — I know how hard you worked to map your USB ports!

I'm still testing the app, so there might be some issues and bugs. Please share your feedback on the generated files and how the app performed on your motherboard configuration.

If you've found this tool helpful and it helped you save time and unnecessary headaches, please support development & updates via PayPal.

Native USB mapping, live from IOKit

USB Ports Mapper is a native macOS app for building USB port maps for Hackintosh systems — the same job tools like USBToolBox, Hackintool, and USBMap do, but as a self-contained app that reads your USB controllers live from IOKit and lets you select, name, and type each port with immediate visual feedback.

It outputs everything you need to actually use the map: UTBMap.kext + USBToolBox.kext (the modern, SMBIOS-independent method), a native USBPorts.kext (the classic Apple-style, SMBIOS-locked method), and legacy SSDT-UIAC.aml / USBInjectAll.kext support, plus the supporting SSDT-USBX and SSDT-EC ACPI tables.

Live IOKit
Real-time controller reading
UTBMap & Native
Multi-format kext export
15-Port Guard
Enforces macOS controller limits
ACPI Aware
Decodes _PLD physical locations

Interface Controls

Header Row & Global Controls

Configure mapping rules, background discovery, and controller limit warnings.

Auto-Discovery (On / Off)
The pill next to the app name. When turned on, the app re-scans IOKit automatically every few seconds so newly plugged-in devices show up without you doing anything. Click it to pause or resume scanning at any time.
SMBIOS Selector
The Mac model identifier you're spoofing (e.g. iMacPro1,1 or MacPro7,1). Only used for the native USBPorts.kext output, since that method is tied to a specific SMBIOS model; the recommended UTBMap.kext method ignores it entirely.
Exclude Field
A comma-separated list of port names (e.g. HS01, SS02) to leave out of the generated map entirely, without having to deselect them one by one across multiple controllers.
Allow More Than 15 Ports
macOS's stock USB driver can only address 15 ports per controller. This toggle tells the app's internal warnings that you've enabled the XhciPortLimit quirk in your bootloader. An interactive stepper lets you raise the warning ceiling up to 26 ports.

Toolbar Actions

Action Buttons & Tools

Diagnostic tools, live ACPI decoders, and comprehensive kext generation.

Build Kext
The main event. Generates a timestamped folder on your Desktop containing UTBMap.kext, bundled USBToolBox.kext, native USBPorts.kext, legacy SSDT-UIAC.aml, SSDT-USBX.aml, SSDT-EC.aml, a usb.json snapshot, and clear Instructions.md.
Detect Port Locations
Reads your board's live ACPI tables and decodes each port's _PLD (Physical Location of Device) data when present, identifying paired HS/SS connectors and panel locations (front panel, rear I/O, internal). Ports with verified ACPI device objects also unlock "Disable via SSDT".
Guess Port Addresses
A diagnostic-only tool separate from your real map. It builds a small USBMapDummy.kext that sweeps a range of raw port addresses so you can discover ports that your motherboard firmware's ACPI tables do not expose cleanly.
Export Debug Info
Writes a comprehensive raw IOKit dump of every controller and port to a JSON + text summary. Essential when requesting troubleshooting help, as it exposes the entire device tree behind every port rather than just the simplified list.
Refresh, Clean & Unhide All
Refresh re-scans IOKit immediately on demand. Clean hides ports that are both unselected and have never had a device attached to simplify large lists. Unhide All restores all hidden ports into view.
Import & Reset
Import loads a previously exported usb.json or an existing kext's Info.plist so you can resume earlier work without starting over. Reset clears your current selections and settings back to defaults with confirmation.

Port List Architecture

Per-Port Row Controls

Each row in the port list displays detailed status feedback and properties from left to right:

Activity Dot & Port Name
The activity dot illuminates solid green while a device is attached and pulses when plugged in. The port name (e.g., HS04, SS02) is selectable and copyable.
Comment Field & On/Off Toggle
Enter free text notes ("Rear IO USB Type C", "Front Panel"). Comments are preserved in generated kexts and SSDTs as #comment. The toggle controls whether the port is included in the map.
Port N & Location Badges
The Port N badge shows the port's raw index encoded into the map. The Location badge (📍) appears when _PLD data is found, displaying physical panel location and companion paired ports.
Disable via SSDT (Bluetooth)
Appears only on ports with a verified ACPI device object behind them. Generates a standalone SSDT that reports that device as not present under macOS — specifically designed to disable built-in motherboard Bluetooth.
Speed & Type Pickers
Override auto-detected speed class or leave on Auto. The Type picker allows setting physical connector types: Type A, Type C (with or without switch), or Internal header for proper sleep and orientation behavior.
Connected Devices Inspector
An expandable sub-row displaying exactly what device is plugged in right now, including product strings, vendor IDs, speeds, and full downstream trees behind external USB hubs.

Mapping Workflow

Typical Workflow

Follow these five steps to build a complete, stable USB port map for OpenCore.

  1. Discover Ports: Hit Refresh (or let Auto-Discovery run) and plug a device into each physical port you care about, one at a time, watching which row lights up.
  2. Select & Exclude: Toggle on the ports you want in your final map; use Exclude for anything you're leaving out entirely to remain under the 15-port limit.
  3. Detect Port Locations: Run Detect Port Locations to auto-fill panel/pairing info and internal classification where your motherboard's ACPI data supports it.
  4. Refine Types & Speeds: Adjust any port's Type or Speed manually where needed (e.g. correcting a Type-C port between "with switch" and "without switch" based on how it actually behaves).
  5. Build Kext & Install: Hit Build Kext, then follow the generated Instructions.md — pick one method (UTBMap.kext + USBToolBox.kext is recommended) and don't mix it with the legacy SSDT-UIAC/USBInjectAll method.

Community & Lineage

Credits & Acknowledgments

USB Ports Mapper stands on the shoulders of remarkable community tooling and research:

Dhinak G & USBToolBox
Pioneered the modern, SMBIOS-independent UTBMap architecture and cross-platform companion drivers that revolutionized Hackintosh USB mapping.
RehabMan
Created the foundational USBInjectAll and SSDT-UIAC mapping methodology that powered early macOS Clover and OpenCore USB configurations.
Acidanthera Team
Developed OpenCore, MaciASL, and the core ACPI/Kext loading mechanisms that underpin modern macOS boot management.
Dortania & CorpNewt
Authors of the quintessential OpenCore Vanilla Mapping Guides and pioneering diagnostic tools including USBMap and SSDT generators.

Compatibility

System Requirements

macOS
Big Sur 11.0 to Sequoia 15.x+
Architecture
Universal (Intel + Apple Silicon)
Privileges
Standard user account (reads live IOKit)
Price
Free
USB Ports Mapper

Build your perfect USB map in minutes.

Live IOKit auto-discovery, 15-port limit enforcement, and instant UTBMap.kext & USBPorts.kext generation.

Download USB Ports Mapper Free ← All Apps

Frequently Asked Questions

Got questions? We've got answers.

What is the difference between UTBMap.kext and USBPorts.kext?
UTBMap.kext (bundled with USBToolBox.kext) is the modern, SMBIOS-independent method that works regardless of what Mac model you spoof. Native USBPorts.kext is the classic Apple-style codeless kext tied to a specific SMBIOS model.
What does Detect Port Locations do?
It reads your motherboard's live ACPI tables and decodes each port's _PLD (Physical Location of Device) data when present, identifying which HS and SS port pairs share a physical connector and whether it is on the front panel, rear I/O, or an internal header.
How can I disable my motherboard's built-in Bluetooth?
Ports that have an identified ACPI device object unlock a "Disable via SSDT" action. This builds a standalone SSDT that reports that specific device as not present under macOS, which is ideal for disabling built-in motherboard Bluetooth modules.
Does 'Allow more than 15 ports' patch macOS automatically?
No. macOS stock USB drivers can only address 15 ports per controller. This toggle tells the app's internal warnings that you have already enabled the XhciPortLimit quirk in OpenCore, allowing you to test and map without triggering false warnings.
How do I open apps blocked by macOS Gatekeeper?
macOS Gatekeeper may flag apps from unidentified developers. To open them, right-click (or Control-click) the app icon and select "Open" from the context menu, or learn more here.