macOS

The Root: /

Several classic Unix paths (/tmp, /var, /etc) are symbolic links into /private. Apple keeps the mutable system state under /private and presents the familiar names as links.

/System and the read-only volume

Since macOS Catalina, the operating system lives on a separate, sealed read-only system volume. The apps you install, your files, and your settings live on a separate Data volume. macOS stitches the two together so they look like one tree, using firmlinks.

The practical effect: you cannot modify /System, even as an administrator. This protects the OS from tampering and makes updates reliable.

The three Library folders

macOS keeps resources at three levels, each in its own Library folder. This mirrors the Windows split between system, shared, and per-user data.

When a resource exists at more than one level, the more specific one wins: user over local over system.

/Applications and the .app bundle

An app on macOS is not a folder of loose files. It is a single .app bundle, which is really a directory that Finder shows as one icon. Right-click an app and choose Show Package Contents to look inside.

A bundle keeps the executable, resources, and metadata together, so installing is often just dragging one item.

/Users and your home folder

Each user gets a home folder at /Users/<username>, also written ~.

Finder hides ~/Library by default. Press Cmd+Shift+. in Finder to reveal hidden files, or use Go > Go to Folder and type ~/Library.

Homebrew: /opt/homebrew vs /usr/local

Homebrew is the de facto package manager for developer tools on macOS. Its location depends on the chip.

This is why a shell config copied from an Intel Mac often cannot find brew on an Apple Silicon Mac. The PATH points at the wrong prefix.

A note on case sensitivity

The default macOS file system (APFS) is case-insensitive but case-preserving. Makefile and makefile are treated as the same name, but the original casing is kept. This trips up projects moved from Linux, where the file system is case-sensitive.

Quick Reference

Syntax

macOS has shipped with zsh as the default shell since Catalina.

Common Variables

The PATH Variable

$PATH is a colon-separated list of folders the shell searches for programs.

/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

When you type git, the shell checks each folder in order until it finds an executable named git. Order matters: earlier folders win. Putting /opt/homebrew/bin first is how a Homebrew tool overrides the system version.

macOS builds the base PATH with a helper called path_helper, which reads /etc/paths and any files in /etc/paths.d. Your shell config then prepends or appends to it.

Where variables are set

Zsh reads different files depending on how the shell starts.

~/.bash_profile and ~/.bashrc are the equivalents if you switch back to bash.

The GUI app gotcha

Variables you export in ~/.zshrc reach programs launched from the terminal. They do not reach GUI apps launched from the Dock or Finder. GUI apps inherit their environment from launchd, not from your shell.

To set a variable for GUI apps, use launchctl:

launchctl setenv MY_VAR value

This is why a tool that works in the terminal sometimes cannot be found by an app launched from the Dock.

Viewing and setting

echo $PATH                    # read one variable
printenv                      # list all variables
export API_HOST=example.com   # set for this session only

To make a variable permanent, add the export line to ~/.zprofile (for PATH) or ~/.zshrc:

echo 'export EDITOR=nano' >> ~/.zshrc
source ~/.zshrc               # apply without opening a new terminal

Quick Reference