FAQ
Installation & Authorization
What permissions does AppPorts need?
AppPorts needs Full Disk Access permission to read and modify the /Applications directory. On first launch, it will guide you through authorization. You can also manually add it in System Settings → Privacy & Security → Full Disk Access.
Which macOS versions are supported?
Minimum support is macOS 12.0 (Monterey). macOS 15.1 (Sequoia) and later additionally support App Store app installation to external drives with in-place updates.
App Migration
How do I scan apps outside /Applications?
Click the "+" button in the "Mac Local Apps" header to add extra scan directories. Useful for tools like JetBrains Toolbox and Steam that install apps in custom locations. Added directories are saved automatically and monitored for changes.
What if the app won't open after migration?
- Confirm external storage is connected and accessible
- Check app status badge: If "Orphan Link," the external app is lost; manual unlinking required
- If a "Damaged" prompt appears, right-click the app and select "Re-sign"
- If still unresolved, select "Move Back to Local" in the External Apps library
What if I see a "Damaged" prompt?
macOS's code signing mechanism detected a change in the app package structure. Resolution:
- Right-click the app in AppPorts
- Select "Re-sign"
- AppPorts will automatically back up the original signature and execute Ad-hoc re-signing
For detailed mechanisms, see Re-signing & Crash Prevention.
Will the app crash if external storage is unplugged?
The local entry (Stub Portal) will attempt to call open to launch the external app. If external storage is not connected, the app cannot launch but will not crash. Normal use resumes after reconnecting external storage.
Can apps be updated after migration?
Depends on app type:
| App Type | Can Auto-Update | Notes |
|---|---|---|
| Native apps (no self-update) | ✓ | Normal updates |
| Chrome, Edge (custom updater) | ✓ | Updates install to local; AppPorts detects a newer local version and tags "Pending Move Out" |
| Sparkle / Electron apps | ✗ | Lock prevents in-app updates; must restore to local via AppPorts before updating |
| App Store apps (macOS 15.1+) | ✓ | App Store can update in-place on external drive |
| App Store apps (macOS <15.1) | ✗ | Manual re-migration required |
What does "Pending Move Out" mean?
"Pending Move Out" means a real local app is newer than the matching copy on external storage. This often happens when a custom updater, such as Chrome or Edge, installs the new version back into /Applications.
You can migrate the app again to replace the old external copy with the newer local version. AppPorts matches by Bundle ID first and falls back to normalized app name when needed. If versions are missing or not comparable, or if same-name apps have different Bundle IDs, the badge is not shown.
Will AppPorts overwrite an existing external target?
Not blindly. AppPorts only auto-cleans the external target when the app is in "Pending Move Out" state, or when the target is recognized as an AppPorts-managed old portal or stale migration remnant. If the external path contains an unrelated real app or directory, migration stops with a destination conflict.
How to migrate App Store apps to external drive?
macOS 15.1+: In App Store settings, enable "Download and install large apps to an external drive," selecting the same external storage as AppPorts.
macOS <15.1: In AppPorts settings, enable "App Store App Migration." After manual migration, app updates require re-migration.
Migration is slow/stuck. What to do?
- At 100% migration progress, there may be a 1-2 second pause while creating local entries
- Large apps (e.g., Xcode, Adobe) take longer to migrate — this is normal
- If stuck for a long time, check external storage connection stability
- USB 2.0 is slow; recommended to use USB 3.0 or above, or Thunderbolt
Data Directory Migration
Will data be lost after data directory migration?
No. AppPorts uses the symbolic link strategy: data is completely copied to external storage first; only after confirming successful copy is the original local directory deleted. Any failed step triggers automatic rollback.
If the external target already exists, AppPorts only continues recovery when .appports-link-metadata.plist fully matches the current source path, destination path, and data directory type. A real directory without matching metadata is treated as a conflict; AppPorts no longer takes it over based on similar size.
When might data directory migration cause app issues?
- Apps using file locks or SQLite WAL logs
- Extended attributes may be lost across symbolic links
- Group Containers directories shared by multiple apps under the same Team
When migrating data under ~/Library/Containers/ or ~/Library/Group Containers/, AppPorts asks whether to Ad-hoc re-sign the associated app after migration. Choose the re-sign option for apps that may fail to recognize moved data or show launch/signature prompts; choose migrate only if you want to leave the app signature unchanged.
How to restore migrated data directories?
In AppPorts' data directory management interface, select the migrated directory and click "Restore." AppPorts will delete the symbolic link and copy data from external storage back to local.
Other
Does AppPorts collect my data?
No. AppPorts runs completely offline and does not collect or upload any user data. Log files are stored locally in ~/Library/Application Support/AppPorts/.
How to report issues?
Please submit on the project Issues page. It is recommended to include a diagnostic package (Menu bar → Logs → Export Diagnostic Package) to expedite issue resolution.