Blog Post

How to Create and Use Symlinks on a Mac

Stay on Top of Enterprise Technology Trends

Get updates impacting your industry from our GigaOm Research Community
Join the Community!

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.

6 Responses to “How to Create and Use Symlinks on a Mac”

  1. Hi Weldon, I did exactly what you said and this did not work for me.

    user-76c9dd:~ glasserp$ sudo rm -rf ~/Downloads/
    user-76c9dd:~ glasserp$ ln -s /Volumes/Macintosh HDD/Downloads/ ~/Downloads
    ln: /Users/glasserp/Downloads: No such file or directory

    Any help please?

  2. If you just wanted to move Home Folder (which does include your Documents, Downloads etc.), would it not be easier to go to the Accounts preference pane and then right click on your User account then click advanced? This then allows you to move your Home Folder in a GUI way.

    • Yes, that absolutely works. However, I didn’t want to move my entire Home folder. I wanted to keep the ~/Library file on my SSD for speed and to make sure I could still boot into my account even if the hard drive failed (and the SSD was still working). So I chose to just move some of the sub-folders.

  3. Does exist an application which can manage symlinks in a GUI-friendly way? (I would use Linux if I wanted to deal with the terminal ;)

    By the way, I very useful article: another good idea is also to use symlinks combined with Dropbox, isn’t it?