Is there a manual or guide to what all of the built-in directories should be used for? Like what is /home/, or /net/?
Take a look at the File System Programming Guide for the most up-to-date information and at
man hier in Terminal, which provides a "historical sketch" of the filesystem hierarchy (it's included at the end of this answer for reference).
A comment to your question mentions the Filesystem Hierarchy Standard. You will probably come to the conclusion, after perusing File System Programming Guide and
man hier, that macOS doesn't follow the FHS, that's more of a Linux thing. Of course, there are similarities between the FHS and the filesystem layout in macOS because of the common UNIX origin, but the differences are striking. macOS doesn't use any of these:
/boot folder -> macOS uses
/System/Library/Kernels instead (in older versions of macOS, the folder containing the kernel was
/home folder -> macOS uses
/root folder -> macOS uses
/opt isn't mentioned not one time in any document (more on
A further distiction between macOS and a FHS-compliant OS is the use of
/private, for example
/etc is a symlink to
/net: It is an automounter map (listed in
/etc/auto_master), see Wikipedia for more information.
What does and should go into /opt/ and what should/does go into /usr/? My understanding is that /usr/ used to be for user home directories, but since that exists in /Users/ - what is the purpose now?
/usr was used in the past to place the home directories of the users, that's no longer the case.
/usr contains user commands (in
/usr/bin for normal users and
/usr/sbin for administrative users, like
root), shared libraries (
/usr/lib), man pages (
/usr/share/man), executables that shouldn't be run directly by users (
/usr/libexec) and other stuff.
It also offers a subdirectory,
/usr/local, to place programs, libraries and other files that don't come with the base OS.
/opt has a very similar role to
/usr/local and they seem interchangeable. However, from my experience working with other Linux/UNIX sysadmins, there seems to be a preference for
/usr/local in BSD-based UNIX OSs.
So this is my take on it: macOS is BSD-based and consequently I'd use
/usr/local. Note that you can create a program directory and then symlink commands to
/usr/local/bin, etc, for example:
/usr/local/bin/mysqladmin -> ../mysql/bin/mysqladmin
/usr/local/lib/libmysqlclient.so -> ../mysql/lib/libmysqlclient.so
This used to be usual practice in Linux and UNIX too, but the FHS explicitely forbids it: if you wish to install third party packages in their own directory hierarchy you should use
/opt/<package> instead. Note that FHS-compliance requires to put configuration files in
/etc/opt/<package> and variable files in
So, in macOS, I'd recommend that you stick to
/usr/local as described above.
I'm aware of add-on software like Cisco VPN and XQuartz that install in
/opt, so the above distinctions start to blur.
As mentioned above this is
A historical sketch of the filesystem hierarchy. The modern macOS filesystem is documented in the
``File System Programming Guide'' available on Apple Developer.
/ root directory of the filesystem
/bin/ user utilities fundamental to both single-user and multi-user environments
/dev/ block and character device files
fd/ file descriptor files; see fd(4)
/etc/ system configuration files and scripts
/mach_kernel kernel executable (the operating system loaded into memory at boot time).
/sbin/ system programs and administration utilities fundamental to both single-user and multi-
/tmp/ temporary files
/usr/ contains the majority of user utilities and applications
bin/ common utilities, programming tools, and applications
include/ standard C include files
arpa/ C include files for Internet service protocols
hfs/ C include files for HFS
machine/ machine specific C include files
net/ misc network C include files
netinet/ C include files for Internet standard protocols; see inet(4)
nfs/ C include files for NFS (Network File System)
objc/ C include files for Objective-C
protocols/ C include files for Berkeley service protocols
sys/ system C include files (kernel data structures)
ufs/ C include files for UFS
lib/ archive libraries
libexec/ system daemons & system utilities (executed by other programs)
local/ executables, libraries, etc. not included by the basic operating system
sbin/ system daemons & system utilities (executed by users)
share/ architecture-independent data files
calendar/ a variety of pre-fab calendar files; see calendar(1)
dict/ word lists; see look(1)
web2 words from Webster's 2nd International
words common words
man/ manual pages
misc/ misc system-wide ascii text files
mk/ templates for make; see make(1)
skel/ example . (dot) files for new accounts
tabset/ tab description files for a variety of terminals; used in the term-
cap file; see termcap(5)
zoneinfo/ timezone configuration information; see tzfile(5)
/var/ multi-purpose log, temporary, transient, and spool files
at/ timed command scheduling files; see at(1)
backups/ misc. backup files
db/ misc. automatically generated system-specific database files
log/ misc. system log files
mail/ user mailbox files
run/ system information files describing various info about system since it was
utmpx database of current users; see utmpx(5)
rwho/ rwho data files; see rwhod(8), rwho(1), and ruptime(1)
spool/ misc. printer and mail system spooling directories
mqueue/ undelivered mail queue; see sendmail(8)
tmp/ temporary files that are kept between system reboots
folders/ per-user temporary files and caches