USBToolBox

USBToolBox

by USBToolBox
Utilities

USB mapping tool for creating custom USB port maps on Hackintosh - supports Windows and macOS

Download GitHub
Advertisement
Advertisement (336×280)

USBToolBox

USBToolBox is a USB mapping tool that makes creating custom USB port maps for Hackintosh simpler. It supports mapping from both Windows and macOS, and generates a custom injector kext tailored to your specific hardware.

Overview

macOS has a 15-port limit per USB controller. To work around this, you need to create a custom USB map that only includes the ports your system actually uses. USBToolBox automates this process by discovering your USB ports and building a kext that maps only the ones you need.

Features

  • Cross-Platform: Supports mapping from Windows 10/11 and macOS
  • Companion Port Detection: Automatically detects USB 2/3 companion ports (Windows only)
  • Port Type Guessing: Makes educated guesses for port types (Windows only)
  • Multiple Output Formats: Can build a map using the USBToolBox kext or native Apple kexts (AppleUSBHostMergeProperties)
  • Multiple Matching Methods: Supports multiple ways of matching USB controllers

Supported Methods

Windows 10 or 11 64-bit are recommended for the full feature set, including companion port binding and port type guessing. Windows 8 may work, but Windows 7 and below will very likely crash. 32-bit is not supported.

Simply download the latest Windows.exe from releases. If Windows Defender or other antivirus complains, you can either whitelist the download or use Windows.zip, which doesn’t have a self-extractor.

From Windows PE

USBToolBox also works from Windows PE. Some device names may not be as descriptive, but if you don’t want to install Windows, you can create a Windows PE USB, press Shift + F10 to open Command Prompt, and run the program.

macOS is not recommended for USB mapping for several reasons:

  • No companion port detection (insufficient information available)
  • No port type guessing
  • Port limits must be dealt with manually
  • In macOS 11.3+, XhciPortLimit is broken, requiring additional workarounds

If you must use macOS, consider using USBMap instead, as it has code to handle the port limit. If you still want to use USBToolBox on macOS, download macOS.zip from releases.

Installation & Usage

  1. Download the appropriate release for your OS from GitHub
  2. Open the tool and adjust settings if necessary
  3. Select Discover Ports and wait for the listing to populate
  4. Plug a USB device into each port. Wait for the listing to show your device before unplugging and moving to the next port
    • On Windows, you only need to plug 1 device into USB 3 ports (companion detection should work automatically)
    • On macOS, you must plug both a USB 2 device and a USB 3 device into each USB 3 port
    • For old computers with OHCI/UHCI and EHCI controllers, plug a mouse/keyboard to map USB 1.1 personalities
  5. Once mapping is done, go to the Select Ports screen
  6. Select your ports and adjust port types as necessary
  7. Press K to build the kext
  8. Add the resulting USB map to EFI/OC/Kexts and update your config.plist
    • If building a map that uses the USBToolBox kext, make sure to also download the USBToolBox kext
    • Remove UTBDefault.kext if you have it
  9. Reboot and your USB map should be working

Troubleshooting

Missing port information

Make sure you have drivers installed for all your devices. On Windows, some information is missing if you don’t have drivers installed, causing USBToolBox to report them as unknown.

Port limit issues on macOS

If you’re mapping from macOS and hitting the 15-port limit, consider using USBMap instead, which has built-in port limit handling.

FAQ

USBToolBox vs USBInjectAll?

USBInjectAll injects all USB ports at once — it’s a blunt tool for discovery. USBToolBox is a modern replacement that lets you discover and map only the ports you actually need, generating a custom kext tailored to your hardware.

USBToolBox vs USBMap?

Both are USB mapping tools. USBToolBox is newer and supports mapping from Windows with companion port detection and port type guessing. USBMap is macOS-only but has better handling of the macOS port limit. For most users, USBToolBox from Windows is the recommended approach.

Do I need the USBToolBox kext too?

It depends on the output format you chose. If you built a map that uses the USBToolBox kext format, you need USBPorts (the USBToolBox kext) installed alongside your map. If you built a map using native Apple kexts (AppleUSBHostMergeProperties), you don’t need it.

  • USBPorts - Companion kext for USBToolBox maps
  • USBInjectAll - Legacy USB port injection (Intel only)

Resources