Mac file system structure: two trees over one disk

The short answer: a Mac stores everything on one APFS container, but that container holds two main volumes. A read only, cryptographically sealed System volume carries macOS itself, and a writable Data volume carries everything else, including your home folder. macOS stitches the two together so they look like a single tree that starts at /. Finder shows a tidy version of that tree with four visible folders (Applications, Library, System, Users). The Terminal shows the full version, including Unix folders such as /usr, /bin and /private that Finder hides on purpose. Most confusion about where a file "really" lives comes from reading one view while thinking about the other.

This guide walks through both views, explains which parts can be changed and which cannot, and ends with a practical rule for where working files belong.

What the disk actually holds: one container, several volumes

Open Disk Utility, or run diskutil apfs list in Terminal, and the startup disk turns out to be an APFS container with several volumes inside it. On a Mac running macOS 27.0.1, checked by the editorial desk on 9 October 2026, the container listed these roles:

Volume role	Name shown	Sealed	What it holds
System	Macintosh HD	Yes	The operating system, read only
Data	Data	No	Users, apps you install, settings, caches
Preboot	Preboot	No	Files needed before macOS starts
Recovery	Recovery	No	The recovery environment
VM	VM	No	Swap files for virtual memory

APFS lets these volumes share free space. Apple's Disk Utility guide on file system formats describes it this way: space inside a container is allocated on demand, and the available space is the container size minus what all volumes use. That is why the System and Data volumes do not each show a fixed size the way old partitions did.

The System volume is more than read only. Apple's Platform Security guide on the signed system volume explains that since macOS 11 every byte of system content is hashed, and the hashes roll up into a single value called a seal. If data read from the System volume does not match its hash, macOS refuses to return it. In practice this means nothing, not even an administrator with sudo, can quietly edit a file under /System and keep booting from it.

So the first piece of the structure is physical: one container, one sealed volume that Apple controls, one writable volume that you control.

How two volumes become one tree

If macOS is on one volume and your files are on another, why does Finder show a single Macintosh HD? The answer is firmlinks. A firmlink is a two way link that the system sets up at boot, so that certain folders on the System volume point into matching folders on the Data volume. /Users, /Applications and /Library look like they sit at the top of the startup disk, but their contents live on the Data volume.

The Data volume is also mounted on its own at /System/Volumes/Data. On the Mac checked for this article, /home is a symbolic link pointing to /System/Volumes/Data/home, which makes the arrangement visible. The same is true for .VolumeIcon.icns at the root, which links to the copy on the Data volume.

Three more links matter for anyone who reads paths in Terminal output:

• /etc points to /private/etc
• /tmp points to /private/tmp
• /var points to /private/var

These are ordinary symbolic links, visible with ls -la /. They exist because macOS keeps the Unix layout that scripts expect while storing the real data under /private. When a log message or an error mentions /private/var/folders/..., it is the same place a script calls /var/folders/....

The practical consequence: two different paths can name the same file. When comparing paths, for example in a backup exclusion list or a script that checks whether a file is inside a folder, resolve links first (realpath in Terminal does this) or the comparison can fail for no visible reason.

Finder's tree versus the Terminal's tree

Finder and the shell read the same disk, but they apply different filters.

Finder hides anything with the hidden file flag, anything whose name starts with a dot, and a set of system paths. Running ls -lO / shows the flags directly. On the Mac checked for this article, /bin, /sbin, /usr, /etc, /tmp and /var carried both restricted and hidden. /private, /cores, /dev and /Volumes carried hidden. Your own ~/Library folder also carries hidden, which is why it does not appear in a home folder window.

Path	Visible in Finder by default	Flag seen with ls -lO	Who should write there
/Applications	Yes	none (sunlnk)	Installers, you
/Library	Yes	none (sunlnk)	Installers, admin tools
/System	Yes	restricted	Apple software updates only
/Users	Yes	none (sunlnk)	Each user, inside their own folder
/usr, /bin, /sbin	No	restricted, hidden	Apple only (except /usr/local)
/private (/etc, /tmp, /var)	No	hidden	System services
/Volumes	No	hidden	macOS, when drives mount
~/Library	No	hidden	Apps, on your behalf

Finder can still reach every one of these. Press Command+Shift+G to open the Go to Folder window, as listed on Apple's Mac keyboard shortcuts page, then type a path such as /usr/local or ~/Library. The window opens even though the folder is hidden in normal browsing.

The restricted flag is the visible sign of System Integrity Protection. Apple's System Integrity Protection article lists the protected areas as /System, /usr, /bin, /sbin, /var and the apps that ship with macOS. It also lists the places third party installers may still write: /Applications, /Library and /usr/local. That list is the most useful single fact in this whole topic, because it tells you exactly where an install script is allowed to put things.

The four domains: why there are three Library folders

Apple's developer documentation, in the File System Basics overview, divides the file system into domains. The idea still explains why the same folder names keep appearing in several places.

• User domain: everything under your home folder, /Users/yourname. Only you (and processes running as you) normally write here.
• Local domain: /Applications and /Library. Shared by every user of this Mac.
• Network domain: resources shared across a managed network. Rare on personal Macs.
• System domain: /System. Owned by Apple and, today, sealed.

Each domain has its own Library folder, and they are searched in order from most specific to least. A font in ~/Library/Fonts is available only to you. A font in /Library/Fonts is available to every account. A font in /System/Library/Fonts came with macOS and cannot be removed.

The same pattern applies to preferences, application support files, launch agents and audio plug-ins. When an app's support article says "delete the preferences file", it almost always means the copy in ~/Library/Preferences, not the one in /Library. When a background helper keeps starting after you remove an app, the leftover is usually a property list in ~/Library/LaunchAgents or /Library/LaunchAgents.

Apple's guide to renaming files names the Library folder, app folders and the home folder as things that should not be renamed. Moving or renaming them is the fastest way to make the domain search fail without any error message.

Inside your home folder: what is meant for you and what is not

The home folder is where the structure becomes personal. It holds the folders Finder puts in the sidebar by default: Desktop, Documents, Downloads, Movies, Music, Pictures and Public. It also holds the hidden ~/Library and, for anyone who uses developer tools, a collection of dot folders such as .ssh, .config and .zshrc.

A few rules of thumb follow from the domains above:

1. Documents and project folders are yours. Nothing in macOS depends on their layout. Rename and reorganize freely.
2. ~/Library belongs to apps. Reading it is fine. Editing files inside it is sometimes necessary for troubleshooting. Building your own folder structure inside it is not a good idea, because apps and macOS updates can clean it up.
3. Desktop and Documents may not be local. If "Sync Desktop & Documents folders" is turned on in Finder Settings, as described on Apple's Finder settings page, those folders are stored in iCloud Drive and may be optimized away when storage runs low. Tools that expect a file to be on disk can then find a placeholder instead.
4. Cloud providers live in ~/Library/CloudStorage. Dropbox, Google Drive and OneDrive mount there under current macOS releases. Finder shows them in the sidebar under Locations or Cloud, which hides how deep they actually are.

Point 4 is easy to miss. A path like ~/Library/CloudStorage/Dropbox/Clients/Acme is perfectly normal, and it explains why a terminal session opened in a Dropbox folder shows a much longer prompt than expected.

Where working files should actually go

With the structure in mind, the placement question has a short answer. Put work in the user domain, outside ~/Library, and keep the tree shallow enough that you can type the path from memory.

A layout that holds up under real use looks like this:

• ~/Documents/ or a dedicated top level folder such as ~/Work/ for active projects
• one folder per project, with the same few subfolders in each (for example brief, assets, delivery)
• external drives and network shares left where they mount, under /Volumes, rather than copied into the home folder
• cloud folders used for files that must sync, and local folders for everything that does not

The weakness of this layout is not the disk. It is the view. A project often spans several roots at once: the brief in Documents, footage on an external drive under /Volumes, shared assets in a cloud folder under ~/Library/CloudStorage. Finder's sidebar can hold a shortcut to each of them, but it cannot show that they belong together, because a sidebar entry in Finder can only point at a folder, not group several folders under one heading. Apple's Finder sidebar guide confirms the model: sidebar items are aliases to a folder, disk or file, and adding one does not move anything.

Two common responses are to move everything into one folder, which breaks sync and fills the internal disk, or to use aliases and symbolic links, which work but are easy to break when a drive is renamed. A third is a file manager that keeps its own map of places on top of the file system. That kind of tool can list a folder on an external drive under a project in Documents without moving a file, which matches how the work is organized rather than how the volumes are mounted. The features page shows one example of this approach, including a terminal that opens in whichever folder is selected.

Reading a path without getting lost

A few habits make the two trees easier to keep straight:

• When Finder and Terminal disagree, trust ls -la. Finder's view is filtered. The shell's view is the real tree.
• Resolve before comparing. realpath turns /var/folders/... and /private/var/folders/... into the same answer.
• Check the volume. df -h . shows which volume the current folder is on. If it says /System/Volumes/Data, the file is on the writable side.
• Read the flags. ls -lO shows hidden, restricted and other flags that explain why something is invisible or refuses to change.
• Do not fight the seal. If an instruction from an old forum post says to edit something under /System, it predates the signed system volume. Look for the modern equivalent in /Library or ~/Library.

If questions remain about how a particular file manager handles hidden folders, cloud storage or external drives, the FAQ covers the common cases.

What to change first

Open Terminal, run ls -lO / and diskutil apfs list once, and compare what you see with the Finder window for Macintosh HD. Then pick one top level folder in your home directory for active work and stop saving projects anywhere else. If a project already spans several drives and cloud folders, a sidebar that can group them, such as the one in Atriens, saves the daily hunt without moving any files.