Fix: Vibium Permission Errors on macOS

Vibium permission errors on macOS almost always come from one of three things: Gatekeeper quarantining the auto-downloaded Chrome for Testing, a cache directory your user cannot write to, or macOS privacy controls blocking screen capture — none of which are Vibium bugs. Vibium ships as a single Go binary and downloads its own Chrome on first run, and macOS treats anything downloaded from the internet as quarantined until it is approved. That quarantine, plus the strict file and privacy permissions macOS enforces, is what produces the "cannot be opened," "operation not permitted," and "permission denied" messages you see at launch. Each has a safe, specific fix that does not require disabling system security wholesale. This guide walks through clearing quarantine, repairing the cache directory, and granting capture permission, with the Python launch you use to verify each fix.

Why does Vibium get a permission error on macOS?

macOS permission errors with Vibium are caused by the operating system's security model, not by Vibium itself. The first run downloads Chrome for Testing, and macOS may quarantine it, refuse a non-writable cache path, or block screen capture under its privacy settings. Identifying which message you got tells you which fix to apply.

from vibium import browser_sync as browser
 
# This first launch triggers the Chrome download — and any permission error
vibe = browser.launch()
vibe.go("https://example.com")
print(vibe.find("h1").text())
vibe.quit()

If this fails with a permission or "cannot be opened" message, work through the sections below in order.

How do I fix "Chrome cannot be opened" (Gatekeeper)?

A "cannot be opened because it is from an unidentified developer" or "operation not permitted" error is Gatekeeper quarantining the downloaded Chrome. Clear the quarantine attribute from Vibium's cache directory so macOS will run the browser.

# Remove the quarantine flag from the downloaded Chrome (cache lives under your home dir)
xattr -dr com.apple.quarantine ~/Library/Caches/vibium

If the cache lives elsewhere on your system, point xattr at the directory where Vibium downloaded Chrome. Alternatively, after a blocked launch, open System Settings, go to Privacy and Security, and click Allow Anyway for the blocked item, then rerun your script. Confirm the exact cache path for your version in the official docs at vibium.com if it differs from the example above.

How do I fix a cache write-permission error?

A "permission denied" error during the first download usually means Vibium cannot write to its cache directory — most often because it was created by sudo earlier and is now owned by root. Restore ownership to your user so the download can complete.

# Give your user ownership of the Vibium cache so it can write Chrome there
sudo chown -R "$(whoami)" ~/Library/Caches/vibium
chmod -R u+rwX ~/Library/Caches/vibium

The lesson behind this fix: install Vibium with pip install vibium as your normal user, not with sudo. Running the installer or your script as root is what creates root-owned files your user later cannot touch. After repairing ownership, run the verification script again and Chrome should download cleanly.

How do I fix screen-capture permission for screenshots?

If screenshot() returns blank or empty images, macOS Screen Recording permission may be blocking the capture for the terminal or app running your script. Grant it in System Settings so Vibium can capture the page.

# Verify screenshots after granting Screen Recording permission
png = vibe.screenshot(full_page=True)
with open("/tmp/page.png", "wb") as f:
    f.write(png)

Open System Settings, go to Privacy and Security, then Screen Recording, and enable the app you launch Python from (Terminal, iTerm, or your IDE). Quit and reopen that app so the new permission takes effect, then rerun. Most page screenshots are captured by the browser engine, but enabling this clears the cases where macOS privacy controls interfere. See screenshot for the full capture options.

How do I verify the fix worked?

Confirm everything is healthy with one clean run that downloads Chrome (if needed), loads a page, reads text, and captures a screenshot. If all four steps succeed, the permission issues are resolved.

from vibium import browser_sync as browser
 
vibe = browser.launch()
vibe.go("https://example.com")
print(vibe.find("h1").text())
with open("/tmp/ok.png", "wb") as f:
    f.write(vibe.screenshot())
vibe.quit()

A successful run here means Gatekeeper has approved Chrome, the cache is writable, and capture permission is granted.

Tips for avoiding macOS permission errors

• Install without sudo — pip install vibium as your user avoids root-owned cache files.
• Clear quarantine with xattr — removes the Gatekeeper flag from the downloaded Chrome.
• Fix cache ownership — chown the Vibium cache back to your user if a sudo run broke it.
• Grant Screen Recording — enable it for your terminal or IDE if screenshots come back blank.

Next steps

• Fix: Vibium headless crashes on Linux
• How to take a screenshot in Vibium
• What is Vibium?