How to Install Homebrew

One of the main features of Homebrew is that it does not require sudo access to install packages. Homebrew installs everything under a local directory, which should be a directory that you own as a user, so you don't need sudo permissions.

The advantage of not needing sudo is that it reduces the risk of damaging system files or installing malware. Only system-wide operations that affect all users require sudo, while operations that only affect your user do not. This approach is safer and more in line with the principle of least privilege, which is a security best practice.

The /usr/local used to be the recommended directory to install Homebrew. However, as of version 2.6.0, Homebrew has changed its default installation directory from /usr/local to /opt/homebrew on macOS systems running on Apple Silicon, also known as the M1 or M2 chip. Homebrew still uses the /usr/local directory for Intel Macs.

You can follow this document to learn how to manually and easily install Homebrew in your local machine using the /opt/ directory.

What's the Difference Between /usr/local and /opt?

In Unix and Unix-like operating systems, such as macOS and Linux, the filesystem is organized in a specific structure. Directories like /usr/local and /opt are part of this structure and each has its own specific purpose.

The /usr/local directory is intended for use by the system administrator when installing software locally. It needs to be safe from being overwritten when the system software is updated. It may be used for programs and data that are shareable amongst a group of hosts, but not found in /usr.

In the context of Homebrew on a Mac, /usr/local used to be the default installation directory. This was because Homebrew installs files to directories that your user owns, so you don't need sudo permissions. macOS leaves /usr/local for the user, so it was considered a safe place to install Homebrew and other software.

The /opt directory is for the installation of add-on application software packages. A package placing files in the /opt directory creates a directory bearing the same name as the package. This directory is the root of the file hierarchy for the specific package.

In the case of Homebrew for macOS, you would have a package named homebrew and all its files would be located in a directory /opt/homebrew. This organization approach makes it easier to compartmentalize add-on software and delete it all at once by removing the appropriate directory when needed.

In a nutshell, the main difference between these two directories is the organization of software. /usr/local is more free-form and software can put files anywhere under /usr/local. On the other hand, /opt is more structured, with each software package residing in its own directory under /opt.

However, the descriptions above are general guidelines and individual system administrators may use these directories differently based on their own preferences or the policies of their organizations.

Install Command Line Tools for Xcode

Homebrew is dependent on Xcode's command-line tools. As such, the first step is to install these tools, if you haven't already, by running the following command in your terminal:

xcode-select --install

How to check if you need these tools?

The only time you might need sudo access with Homebrew is if you're trying to install it in a directory that you don't have write permissions to. But if you're installing it in the usual /usr/local directory, then you don't need to use sudo.

Create the Installation Directory

You need to create a directory for homebrew subdirectory in the /opt directory and change its ownership to your user. This the only section where you need to use sudo and enter your macOS system password. However, you will be doing so in full control and awareness of the sudo operations: you are only creating a directory and changing its ownership.

Run the following command to create the directory:

sudo mkdir /opt/homebrew

Next, run the following command to change its ownership:

sudo chown -R $(whoami) /opt/homebrew

This command changes the owner of /opt/homebrew and all its subdirectories (-R stands for recursive) to the current user ($(whoami) prints the username of the current user).

Download and Unpack Homebrew

Download the latest Homebrew version from its GitHub repository and unpack it in your local machine on the /opt/homebrew directory:

cd /opt/homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew

Let's break down this command:

• cd /opt/homebrew
  • You make the /opt/homebrew directory your current directory: cd /opt/homebrew.
    • The cd command stands for change directory.
• && curl -L https://github.com/Homebrew/brew/tarball/master
  • You use the logical AND operator, &&, to chain commands so that the curl command so that macOS only executes the curl command if the cd command is runs successfully.
  • You then use curl to fetch the compressed content from the master branch of the Homebrew GitHub repository.
    • This compressed content is known as a "tarball".
    • The -L option tells curl to follow any redirects, which you'd need as GitHub will redirect your request to the latest version of the Homebrew.
• | tar xz --strip 1 -C homebrew
  • You use the pipe operator, |, to pass the output of the curl command, the tarball or compressed file, to the tar command.
  • The tar command uncompressed the content into the homebrew subdirectory.
    • The xz option tells tar to extract (x) the file and that it's compressed with gzip (z).
    • The --strip 1 option tells tar to strip the first directory level from the file paths in the tarball.
      • The tarball has a top-level directory, such as Homebrew-brew-xyz/, that you don't need to keep.
    • Your current directory is /opt/homebrew from the cd you run at the start. As such, the -C homebrew option changes into the homebrew subdirectory before unpacking the tarball.

With the Homebrew download and extraction complete, your next step is to add Homebrew to your PATH so that you can access the brew command from anywhere in your terminal. You can use the following command to add a line to your ~/.zshrc file:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc

Finally, run the source command to reload the profile file so that the changes take effect immediately:

source ~/.zshrc

You can now verify that you have installed Homebrew correctly by running the following command:

brew --version

If Homebrew has been installed correctly, this command will print the version of Homebrew that you've installed.

Troubleshooting Homebrew Installation

You may encounter a Permission Denied error when you try to write to that /opt/homebrew directory for the following reasons:

• The /opt/homebrew directory isn't writable by your user.
• Another process is currently using the directory.

You can take these steps to resolve this issue if it happens:

Check the permissions of /opt/homebrew

Run the following command in the terminal:

ls -ld /opt/homebrew

The output should look similar to this:

drwxrwxr-x  12 root  admin  384 Jul  25  2023 /opt/homebrew

Let's break down the example above:

• root is the owner of the /opt/homebrew directory.
• admin is the group.
• drwxrwxr-x are the permissions.
  • The d indicates that this is a directory.
  • The next three characters (rwx) are the owner's permissions: the owner can read (r), write (w), and execute (x) files in the directory.
  • The next three characters are the group's permissions, which as the same as the owner's: (wxr).
  • The last three characters are the permissions for all other users: all other users can read (r) and execute (x) files in the directory; they cannot write any files as the write permission (w) is replaced by a dash (-), which removes that permission.

Following this example, you may not have the necessary permissions to write to /opt/homebrew if your user is not root or part of the admin group, or if the permissions don't allow for writing, (w). If that's the case, you need to change the permissions of the directory.

Change the permissions of /opt/homebrew

If you don't have the correct permissions, you can change them using the sudo chown command. This command changes the ownership of the /opt/homebrew directory to your user. Here's how you can do it:

sudo chown -R $(whoami) /usr/local

This command changes the owner of /opt/homebrew and all its subdirectories (-R stands for recursive) to the current user ($(whoami) prints the username of the current user). You'll need to enter your password since this command uses sudo.

Check for other processes

If another process is using the /opt/homebrew directory, you might get a Permission Denied error. You can check for other processes using this directory by running the following command in the terminal:

lsof +D /usr/local

If this command returns any output, it means that some processes are using the directory. You might need to stop these processes before you can write to the directory.

sudo mkdir homebrew

curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew