Troubleshooting

How do I fix my zsh completions?#

End-users using zsh will see a warning when using brew after installing Workbrew that states: console zsh compinit: insecure directories and files, run compaudit for list. Ignore insecure directories and files and continue [y] or abort compinit [n]? This happens because zsh treats files owned by a different user as potentially unsafe. Since Workbrew manages Homebrew under the workbrew user, zsh flags the completion files as insecure. This is a known zsh behavior and not an issue with Workbrew itself. Users who rely on brew completions will need to apply a fix to prevent these warnings from appearing. To resolve this, users should add the following to their ~/.zprofile: zsh echo 'autoload -U compinit && compinit -u' >> ~/.zprofile source ~/.zprofile This ensures that zsh initializes completions while bypassing security checks for Workbrew-managed files and reloads the user's ~/.zprofile file immediately. If the user is on Ubuntu, they may also need to add: zsh echo 'skip_global_compinit=1' >> ~/.zprofile source ~/.zprofile This prevents the system zsh configuration from running compinit without -u, which would reintroduce the warning. If a user also has nvm installed, they must run autoload -U compinit && compinit -u before nvm initializes completions to avoid conflicts.

How should I add Workbrew and Homebrew to the PATH on a Device?#

Users should add eval $(/opt/workbrew/bin/brew shellenv) to their shell startup configuration. If users already have eval $(/opt/homebrew/bin/brew shellenv) in their shell startup configuration, that will also work.

How does Workbrew handle brew services?#

Workbrew will attempt to stop all existing brew services on installation. After installation, Workbrew will run all (non-root) services as the workbrew user.

I get permissions errors when running for example brew update#

You need to run brew through /opt/workbrew/bin/brew, and not /opt/homebrew/bin/brew or /usr/local/bin/brew. Please see the How should Workbrew and Homebrew be added to the PATH on a Device?.

I get permission errors when attempting to write to Homebrew's installation directories e.g. /opt/homebrew or /usr/local#

With Workbrew, the Homebrew directory is intentionally not writable by non-workbrew users. Instead, configure your tools to write to your HOME directory. See below for instructions for npm. If you need help with other tools, please contact us and we'll help.

npm install -g fails with EACCES errors#

npm install -g fails with EACCES errors because the npm global install directory isn't writable by non-workbrew users under Workbrew. Please configure npm install -g to install into your HOME directory using the following steps:

1. Create the npm global directories under HOME: mkdir -p ~/.npm-global/bin ~/.npm-global/lib 2. Configure npm to use the directories created above: npm config set prefix '~/.npm-global' 3. Add your npm global directory to PATH: export PATH="~/.npm-global/bin:$PATH" See the npm documentation for more details.

After Xcode updates, brew fails with “license not accepted”#

Some macOS updates or App Store auto updates might reset the Xcode license. Until the license is accepted again, brew commands and Workbrew Agent check-ins may fail. Console admins can remediate this by deploying the following script via their MDM:

if /usr/bin/xcrun -find xcodebuild >/dev/null 2>&1; then
  if ! /usr/bin/xcodebuild -license check >/dev/null 2>&1; then
    /usr/bin/xcodebuild -license accept
  fi
fi ```