USBAlias requires macOS 26.5 or later. It runs as a menu bar utility. Open Settings from the menu bar icon or press Command-,.
Getting started
- Connect the USB serial device you want to name.
- Open USBAlias and choose Rules, then Add Rule.
- Select the attached device. USBAlias fills in its product, manufacturer and serial number.
- Give the rule an alias such as
ESP32_LAB, then save it. - Use the alias in your terminal, IDE or script instead of the changing
/dev/cu.*path.
For two identical boards, match on serial number. Product and manufacturer matching is useful when any board of a particular model should share one alias.
Where aliases are stored
Open Settings > General > Aliases to see the folder used by your rules. The App Store version is sandboxed, so it maintains links in a folder you explicitly choose. Older rules may still refer to a path that was configured before sandboxing.
If a script expects an old /tmp/... path, use the supported shim option in Settings to recreate those paths as links into the managed aliases folder.
Common fixes
My alias is not updating when I reconnect the device
Confirm USBAlias is running in the menu bar. Open the Log and check that the device is detected and matched. If it is a new model or serial number, update the rule criteria.
A /tmp path stopped working
The sandboxed App Store version cannot write directly to /tmp. Choose an aliases folder and use the shim option in Settings if existing tools still need the old path.
Notifications or sounds are not appearing
Check the toggles under Settings > General. For notifications, also check System Settings > Notifications > USBAlias and confirm alerts are allowed.
How should I match a specific board?
Use the device picker and keep serial-number matching enabled. That distinguishes two boards that otherwise have the same product and manufacturer.
Does the app need to stay open?
Yes. USBAlias maintains the links while it is running. Turn on Launch at Login under Settings so it starts with your Mac.
How do I see what the app is doing?
Open Log in USBAlias. The activity log records device connections, rule matching, link creation and the current device path.
Diagnostics and privacy
USBAlias does not need network access for aliases or device matching. It offers an optional anonymous diagnostics choice on first launch. Don't Share is the default; nothing is sent before you answer.
If you choose to share, the app sends launch and running heartbeats plus fingerprint-only crash records. USB product names, serial numbers, device paths, aliases, rules and file paths are never included. You can change the choice under Settings > General > Privacy.
Read the full USBAlias privacy policy.
Contact
For support, include your macOS version, USBAlias version and a short description of what the Log shows. Do not include device serial numbers you do not want to share.