[macOS] Install guide

[SenpaiHunters]

macOS Installation Guide for Zen Browser

Initial Setup

Step 1: Download the Latest Version

1. Download the latest Zen Browser DMG.
2. Once downloaded, open the DMG file. You might need to zoom out a bit to see everything.

Step 2: Install Zen Browser

1. Drag the Zen Browser icon to the Applications folder.

Note for Developers

If you are the developer of Zen Browser, ensure you include the following icon sizes for macOS, and update the names accordingly:

• Black-16.png
• Black-32.png
• Black-64.png
• Black-128.png
• Black-256.png
• Black-512.png
• Black-1024.png

These icons serve different purposes, such as the DMG and app icon (1024), Finder icon (128), etc.

Step 3: Bypass Gatekeeper

Upon trying to open Zen Browser, you may encounter a message indicating the file is damaged. This happens because the app does not have a valid developer signature and is using an Ad-hoc sign.

To bypass this warning:

1. Open Terminal.

2. Run one of the following commands:

   To bypass Gatekeeper for the current installed version:

   xattr -c '/Applications/Zen Browser.app/'

   To bypass Gatekeeper for all versions of the app:

   xattr -d com.apple.quarantine '/Applications/Zen Browser.app/'

3. After running the command, if successful, Terminal will return a blank line.

Step 4: Open Zen Browser

1. Open Zen Browser from the Applications folder.
2. Complete the onboarding process.
3. If you use Little Snitch (LS), accept or block any connections as needed, though for a browser, it is generally not recommended to block connections other than telemetry.

Step 5: Restart Zen Browser

At the time of writing, there seems to be a bug with Zen Browser where the menu might not display correctly on the initial start. To fix this, quit Zen Browser (⌘Q) and reopen it.

You should now have a fully functional Zen Browser on your macOS. If you need to uninstall Zen, you can use Pearcleaner.

[mauro-balades]

woah, thanks a lot for this detailed guide! Ill pin it to the repo's issues and add it to the readme. By the way, any idea on why you have to do the terminal thing? Does macos consider it a virus?

[SenpaiHunters]

macOS flags unsigned apps from unidentified developers as potentially unsafe, hence the warning. This isn't because it considers Zen a virus, but because it doesn't recognise the developer. Running the terminal commands bypasses Gatekeeper, allowing the app to run. To avoid this, you can get an official Apple developer certificate and sign the app (although this will cost 100 USD, so for something such as this, would not exactly be viable, hence why we use terminal commands).

[mauro-balades]

that sucks :(

[emm312]

in my experience the corrupted thing can be fixed with a chmod +x on the executable itself and from there you get past the unidentified developer thing in settings

[SenpaiHunters]

in my experience the corrupted thing can be fixed with a chmod +x on the executable itself and from there you get past the unidentified developer thing in settings

chmod +x is for a file to allow execution. For an app in the applications folder you need to pass xattr -c. As this is a dmg, chmod +x works less than the method above.

[estrobink8]

(the first command xattr -c '/Applications/Zen Browser.app/' works though). any ideas on how i can fix this? macOS 14.5 here.

[mauro-balades]

It's one command or the other, not both. The command you just ran clears the attributes so it should work already. (Someone tell me if I'm wrong)

[chilikasha]

hi @mauro-balades , could you please update the icons?

thanks for the browser, enjoying so far!

[stairjoke]

Honestly, I would have loved to try, but the instructions to circumvent security measures are a real turn-off. I understand why, I get it intellectually, but I think its a bad decision, in my opinion.

[mauro-balades]

a bad decision to do what exactly?

[petedermott]

I would love to try Zen for real but skipping what looks to be a pretty key security feature of MacOS is throwing up all kinds of red flags.

Could we donate somewhere so you could pay for the developer certificate and signing process?

[mauro-balades]

Sure, you could donate here, but they cost 100 euros

https://developer.apple.com/support/enrollment/#:~:text=The%20Apple%20Developer%20Program%20annual,currency%20during%20the%20enrollment%20process.

[roblabla]

You can just do right click -> open on the .app, and then you'll get an option to start the app. This just needs to be done on the first run. No need to drop down to the terminal.

[foxt]

Upon trying to open Zen Browser, you may encounter a message indicating the file is damaged. This happens because the app does not have a valid developer signature and is using an Ad-hoc sign.

That's not what that message means.

"This application is damaged and cannot be opened" means the app has a signature, but it's not valid (it's not trusted, the app has been tampered with, or is app was ad-hoc signed by another machine ). macOS does not give users the option to bypass this warning because it assumes the application has been tampered with.

Applications shouldn't be distributed with an ad-hoc signature, because that is not what ad-hoc signatures are designed for. (see: https://apple.stackexchange.com/questions/288291/what-are-the-restrictions-of-ad-hoc-code-signing#317002)

Instead, developers that don't have a certificate that is trusted on the machines they want to distribute to shouldn't code sign the apps at all, then your users will get a message that says 'The developer of this application cannot be verified' and will allow the users to open the app (via right-click open) without resorting to tricking the system into believing it doesn't need to check it.

$ codesign -dv /Applications/Zen\ Browser.app/
Executable=/Applications/Zen Browser.app/Contents/MacOS/zen
[...]
Signature=adhoc 
[...]

$ open /Applications/Zen\ Browser.app/
(get the '"Zen Browser" is damaged' error)

(delete and re-copy from DMG)

$ codesign --remove-signature /Applications/Zen\ Browser.app/
$ codesign -dv /Applications/Zen\ Browser.app/
/Applications/Zen Browser.app/: code object is not signed at all

$ open /Applications/Zen\ Browser.app/
(“Zen Browser.app” cannot be opened because the developer cannot be verified.)
(user can now right-click open, like any other unsigned Mac app)

[figuernd]

Hey I was excited about Zen. I like Firefox, and care a lot about UX. I suspect a lot of users that care about UX will also be using OSX.

But few users will bother to search out this workaround. Instead of acquiring users, your marketing site is a user-journey to a dead end. You would be better off not advertising OSX support in the first place.

[proevilz]

Having to install third party software to uninstall it is a major red flag and a turn off.

[thezacharytaylor]

I didn't have this issue on the lastest? I'm running Sonoma 14.5 on a M1 Pro.

[bravecrayon]

I'm liking it, but the install instructions on the website don't indicate that we must xattr -c the app. Had to dig to find this issue. Hopefully enough donations can happen so that the 100€ Apple Developer account can be covered for a year.

Edit: I see now that the website does link to this issue. Sorry.

[RobertBoes]

For the meantime, as @foxt mentioned, can the ad-hoc signature be removed? Then people can install the app as normal, they'll receive a popup, just like a lot of other open-source apps. There's no need to disable gatekeeper for this really. Either sign the app with a certificate, or not sign it.

The ad-hoc signature doesn't provide any value and having to use xattr to be able to use the app is just a huge no-go for less tech-savvy people.

[IronBlossom]

Hold ctrl, and right-click >> Open

You should have the option to open it.

[Doomsk]

As @foxt and @RobertBoes mentioned, I'll be waiting for a non ad-hoc signature to test the browser.

A friend suggested Zen to me and, since I didn't install Arc browser because it's Google's Chrome in all its telemetry-and-data-collection-with-no-shame mode, I was keen to new experience and UI, away from the always-the-same already established browsers.

[Kiki0fCalifornia]

woah, thanks a lot for this detailed guide! Ill pin it to the repo's issues and add it to the readme. By the way, any idea on why you have to do the terminal thing? Does macos consider it a virus?

@mauro-balades If you could remove the ad-hoc signature—even to leave it without a signature at all—it shouldn’t be a problem. There are lots of apps I have on my mac that don’t have a signature, it is fine and there is no big workaround like this needed, it’ll just say the developer can’t be identified and on the first launch the user will need to right click to open it—something virtually any MacOS user who would find this browser in the first place will be very familiar with because most apps we download online are like that because people don’t want to pay that license.

This is why the Intel Mac version of Zen Browser does not have this issue while the Apple Silicon one does, the Intel version is unsigned whereas this version has the ad-hoc signature, which is not how Mac Apps are supposed to be distributed. Just leave the signature blank like you did for the Intel Mac release and this problem should go away, opening up the app to a lot more users.

[mauro-balades]

How could I remove it? Any guides?

[NathanielH-snek]

How could I remove it? Any guides?

I'm currently looking into the firefox docs, will update with instructions to remove build signing soon, however it looks like you may want to sign with an official apple dev account for some features anyway. See This

Edit: It seems like builds shouldn't be signed unless explicitly called, and I don't see this anywhere but I admittedly don't fully understand your build process.

[NathanielH-snek]

@SenpaiHunters
BTW how do you get this nice graphical image of the app properties?

[codenyte]

@SenpaiHunters BTW how do you get this nice graphical image of the app properties?

@NathanielH-snek It's an app called Apparency

[mauro-balades]

Heya, i've finally gotten the license keys, ill release today with them included!

[HarryHeres]

Heya, i've finally gotten the license keys, ill release today with them included!

LMK when you include them, I will update Homebrew so the xattrworkaround is not needed anymore.

[mauro-balades]

If version 35's build passes this night (ill be sleeping), then you can remove them, they are signed now

[mendelgordon]

it looks like you may want to sign with an official apple dev account for some features anyway. See This

Thanks-that explains why iCloud passkeys aren't working in the current build, and why all Apple silicon builds are ad-hoc signed

[AlternateRT]

If version 35's build passes this night (ill be sleeping), then you can remove them, they are signed now

@mauro-balades It looks like something has gone wrong with the signing. I just downloaded the macos-64x.dmg of a35 and I still get the "Zen is damaged .. move it to the Trash" dialog.

[mjskraju]

@mauro-balades I can confirm what @AlternateRT has mentioned above. The new Alpha build - 1.0.0-a.35 (2024-09-03) build still shows the same dreaded message on Mac. I'm on MacOS Sonoma 14.6.1

[mauro-balades]

Yes, please stop pinging me, ill look more into it... The workflow succeeded when signing the macos app so idk what's going on

[sergio-lopez93]

i actually have made all the steps you said for running it and skiping the damage problem, i used the terminal and wrote what u said etc.. but still zen browser doesnt work.

[Daniel-Kelvich]

Mac M1. "Zen is damaged" issue still persists.

[mauro-balades]

im still working on it, I think I just need to notarize the dmg...

@sergio-lopez93 is there any terminal output?

[mauro-balades]

Update: Once 38 is out, I want this issue gone out of existance... It works!

[SJ50]

Just installed 39, no need of work around. Also Touch ID works with 1Password as well.

[mendelgordon]

I have 39 installed and still can't use icloud passkeys in zen - should I make a new issue?

[muffn]

Just installed 39, no need of work around. Also Touch ID works with 1Password as well.

can't confirm, are you sure about that? Desktop App and Extension still don't sync for me, but further discussion of that is better placed here anyways probably: #856

Edit: It works when I follow the 1Password Guide to add the browser manually by going into the mac app -> settings -> browser and add it there 🥳