If the BitBoxApp fails to install or open on macOS, the issue is usually caused by an incomplete download, a macOS security prompt, launching the app from the disk image, an older copy in another folder, or an installation that did not replace the previous version.

Complete the basic checks below, then use the troubleshooting section that matches the macOS message or behavior you see.

Before you begin

1. Check whether your macOS version is supported. Unsupported or outdated macOS versions can prevent the BitBoxApp from installing or opening correctly. Check the supported operating systems for the BitBoxApp to confirm that your macOS version is supported.
2. Update macOS. Install the latest macOS update available for your Mac. This helps ensure compatibility with the latest BitBoxApp version and allows macOS security features to work as expected.
3. Restart your Mac. Restarting macOS can resolve temporary launch issues, release files that are still in use, and complete pending update processes.

Troubleshooting

macOS reports that the BitBoxApp was downloaded from the internet

This notification is expected the first time you open an application downloaded from the internet. It does not indicate an installation failure.

1. Confirm that you downloaded the BitBoxApp from the official BitBox download page.
2. Select Open in the macOS dialog.
3. Continue using the BitBoxApp.

macOS should remember this confirmation for future launches of the same app.

macOS cannot verify the BitBoxApp

macOS Gatekeeper may display a message such as Apple could not verify the BitBoxApp or BitBoxApp cannot be opened because Apple cannot check it for malicious software. This is a macOS security check for software downloaded outside the App Store, not proof that the installation failed.

Only override a macOS security prompt if you downloaded the BitBoxApp from the official BitBox download page. For additional confirmation, advanced users can verify the BitBoxApp download signature on macOS.

1. Try to open the BitBoxApp once, then close the warning dialog.
2. Open the Apple menu and select System Settings.
3. Select Privacy & Security.
4. Scroll to the Security section.
5. Find the message that the BitBoxApp was blocked and select Open Anyway.
6. Enter your macOS login password if requested.
7. Select Open when macOS asks for confirmation again.

The BitBoxApp should now open and be saved as an allowed exception in macOS.

The BitBoxApp starts from the disk image instead of Applications

Opening the BitBoxApp directly from the mounted DMG can cause update problems and leave multiple app copies on your Mac.

1. Close the BitBoxApp.
2. Open the mounted BitBoxApp disk image in Finder.
3. Drag the BitBoxApp into the Applications folder.
4. Select Replace if macOS asks whether to replace an existing version.
5. Open the BitBoxApp from Applications.
6. Eject the BitBoxApp disk image in Finder.

The BitBoxApp should now start from the Applications folder.

The downloaded DMG file does not open

An interrupted or corrupted download can prevent the DMG file from opening.

1. Delete the downloaded BitBoxApp DMG. If it came from an unofficial source, do not open it.
2. Download the latest macOS version from the official BitBox download page.
3. Open the new DMG file.
4. Drag the BitBoxApp into the Applications folder.

The new DMG should open normally and allow you to complete the installation.

macOS reports that the BitBoxApp is damaged

A message such as The application is damaged and cannot be opened can indicate that the download or application bundle is corrupted or incomplete.

Do not override a damaged-app warning for a BitBoxApp file downloaded from an unofficial source. Delete the file and download the BitBoxApp again from the official BitBox download page.

1. Move the BitBoxApp from Applications to the Trash.
2. Delete the downloaded BitBoxApp DMG.
3. Download a fresh DMG from the official BitBox download page.
4. Open the new DMG.
5. Drag the BitBoxApp into the Applications folder.
6. Open the BitBoxApp from Applications.

The newly downloaded BitBoxApp should now open without the damaged-app warning.

The BitBoxApp closes immediately after opening

An incomplete installation, a corrupted download, or a temporary macOS issue can cause the BitBoxApp to close immediately.

1. Restart your Mac.
2. Try to open the BitBoxApp again from Applications.
3. If it still closes, move the BitBoxApp from Applications to the Trash.
4. Delete the downloaded DMG.
5. Download a fresh macOS DMG.
6. Repeat the steps to install the BitBoxApp on macOS.

The BitBoxApp should now remain open after launch.

The BitBoxApp does not start after updating

A previous BitBoxApp process may still be running, the update may not have completed, or the existing application may not have been replaced.

1. Quit the BitBoxApp completely.
2. If the BitBoxApp does not close, open Activity Monitor, select the BitBoxApp process, and stop it.
3. Restart your Mac.
4. Download a fresh macOS DMG.
5. Open the DMG and drag the BitBoxApp into Applications.
6. Select Replace when macOS asks whether to replace the existing app.
7. Open the BitBoxApp from Applications.

The updated BitBoxApp should now start normally.

The BitBoxApp still shows the old version

This usually means that the previous app was not replaced, multiple BitBoxApp copies exist, or macOS opened a copy from Downloads or the mounted disk image.

1. Close every open BitBoxApp window.
2. Eject any mounted BitBoxApp disk image.
3. Check Applications, Downloads, and other folders for duplicate BitBoxApp copies.
4. Keep the latest BitBoxApp in Applications and move obsolete copies to the Trash.
5. Open the BitBoxApp from Applications, then open Settings → About.
6. Compare the displayed BitBoxApp version with the latest stable BitBoxApp release in the official GitHub repository.
7. Only if the versions do not match, download the latest DMG again.
8. Drag the latest BitBoxApp into Applications and select Replace.
9. Open the BitBoxApp from Applications.

The version shown in Settings → About should match the latest stable BitBoxApp release published in the official BitBoxApp GitHub releases repository. If it does, you are running the latest installed version.

If your BitBox is not detected after installation

If the BitBoxApp opens but does not detect your BitBox, the installation itself is normally complete. Follow the steps to troubleshoot BitBox detection on macOS.

Frequently asked questions

Is the downloaded-from-the-internet message an error?

No. macOS displays this confirmation the first time you open many applications downloaded outside the App Store. Confirm it only after checking that you downloaded the BitBoxApp from the official BitBox download page.

Why does macOS say that Apple cannot check the BitBoxApp?

Gatekeeper displays this warning when macOS cannot complete its normal verification. After confirming that the DMG came from the official BitBox download page, open System Settings, select Privacy & Security, and use Open Anyway in the Security section.

Should I run the BitBoxApp from the DMG?

No. Copy the BitBoxApp to Applications and open it from there. Running it from the mounted disk image can create duplicate copies and cause update problems.

Do I need to delete the old version before updating?

Usually not. Drag the latest BitBoxApp into Applications and select Replace. If the old version still appears, remove duplicate copies and repeat the installation.

Is the installation different on Intel and Apple Silicon Macs?

No. The standard DMG installation workflow is the same on Intel and Apple Silicon Macs. Include your Mac type when contacting support because it can still help diagnose startup problems.

Will reinstalling the BitBoxApp remove my funds?

No. Reinstalling the BitBoxApp does not remove your funds. Your cryptocurrencies remain on their respective blockchains, while access is secured by your BitBox and wallet backup.

Why does the BitBoxApp open but not detect my BitBox?

If the BitBoxApp opens, installation is normally complete. Follow the steps to resolve BitBox detection problems on macOS instead of repeating the installation.

Contact BitBox support

If none of the troubleshooting steps resolves the issue, contact BitBox Support through the official Support contact form.

Include as much of the following information as possible:

• Your macOS version.
• Your Mac model and whether it uses an Intel processor or Apple Silicon.
• The BitBoxApp version, if known.
• The exact macOS error message.
• A screenshot of the error dialog.
• Whether the DMG opens and whether the BitBoxApp was copied to Applications.

This information helps BitBox Support identify the cause more quickly.