How to Create and Use Symlinks on a Mac

In my recent post about pairing SSD and HDD storage inside a MacBook Pro(s aapl), I used a little-known command line feature to redirect some of my user folders from the SSD to the hard drive. I wanted OS X to still refer to the default locations of ~/Documents, ~/Downloads and so on for these folders, but I wanted to use the storage space on the big drive for these kinds of files. Symbolic Links (symlinks) are a function of the UNIX underpinnings of OS X to create something like an alias, but at a low-level in the filesystem.


Aliases were introduced in Mac OS System 7 and were then carried forward to Mac OS X. They are a pointer to a file or a folder somewhere else, even on a server. The alias is tied to the unique ID of that file and will continue to work even if you move the original file or folder because it stores this information (and more) in the resource fork of the alias file. Unfortunately, you may have noticed that some applications do not follow aliases properly.

Symbolic Links (or symlinks)

Symbolic Links are an older feature that harken back to the BSD roots of Mac OS X. These files simply contain the path of the target file or directory stored as text. If you move the target file, the symlink will break because it still points to the original location in the link. However, symlinks work at a low-level such that almost all applications and OS features will follow them to the target.

A Note on Hard Links

The “ln” command below is used to create hard links. “ln -s” makes symbolic links. You can read more about hard links on Wikipedia, but we don’t want to use them here. Be sure to use the “-s” switch when you enter the “ln” commands.

The Home Folder

The User folder in OS X contains several important sub-folders for different types of content. The system expects to find those directories inside the user’s home folder. On installation, OS X created my home folder in the default location on the boot drive, which is the SSD. I then used symlinks to replace some of the default sub-folders with pointers to a location on the secondary hard drive. The “~/” notation, used frequently in the steps below is a shortcut to the current user’s home folder. It is the same as entering “/Users/jack” if the short name of the current user account were “jack” on that machine. The notation “~/Downloads” refers to the Downloads folder inside the current user’s home folder. So “~/Downloads” would be the same as “~/Users/jack/Downloads” in our example. You can use the “~/” notation and you will be sure to refer to your own current user folder.

The ~/Library folder

~/Library deserves some discussion because the contents of this folder are both critically important and not very well understood. The user library (~/Library) contains application preferences, settings, and data. The preferences files are generally small, but are read each time an application launches. The data files could be a different story. Mail keeps all your messages inside ~/Library/Mail/ which can grow to be quite large if you have a several email accounts and a lot of email correspondence. My Mail folder is about 10GB, for example. Steam stores game files down inside the Library as well. Be careful when working with your ~/Library folder, but you may find some large folders that could be better off moved elsewhere.

Steps to Create a Symlink

Here are the steps to create a symlink for the ~/Downloads folder. First step is to make sure that the destination folder is in place. I did this by copying my old Downloads folder from the previous system drive (moved to an external drive enclosure) to the new internal hard drive so it could be found at /Volumes/Bucket/Downloads (“Bucket” is the name of my hard drive). Next, remove the existing Downloads folder (make sure it is empty first). You can’t create a symlink file if another file in that directory has the same name . I use “sudo” to override the normal protections because OS X wants to keep this folder in its usual location. You will be prompted for your password after you enter the following command…

[code] sudo rm -rf ~/Downloads/ [/code]

The next line creates the symlink with the “ln -s” command and sets the target location to “/Volumes/Bucket/Downloads/” and creates the link file at “~/Downloads” in the home folder. If you are following along on your own machine, you will need to replace “Bucket” with the name of your hard drive.

[code] ln -s /Volumes/Bucket/Downloads/ ~/Downloads [/code]

You could also do something like “/Volumes/Bucket/Links/myname/Downloads” so that you have a directory structure to accommodate multiple users. Your other users could also put their folders in the “Links” directory. Just don’t use “Users” at the root level of the hard drive.

After the symlink is in place, any browser (or other application) that tries to write to ~/Downloads will actually save the file to the linked location on the hard drive. When you look in your home folder, you will see Downloads with an alias icon. Just remember that it’s not an alias, it’s a symlink.

Repeat this process for the other folders that you want to keep on the secondary (non-booting) hard drive.