qr code


Bill Gates touched my MacBook Pro

MacOS Home Directory

[ tutorial ]


A funny (not) thing happened the other day. My beloved Thinkpad slipped off the edge of a chair. It wasn’t a big fall and it fell to a carpeted floor so all seemed fine. But the next day I went to plug something into one of the USB-C ports and discovered it was just an empty hole. When the laptop fell, the power connector was in and it pushed the USB-C port in and seemingly broke it right off. Luckily there are two of them, so it all works fine and charges OK. But I plan on taking it in to see if I can get it repaired. I know it will be in for a few days, so I’m prepping my Mac Book Air to serve as a backup.

What I use the Thinkpad for is mostly my personal coding stuff as well as browsing, media consumption, etc. My biggest concern was having a functional coding setup for my creative coding projects and any other learning / exploration I want to do. I pretty much had everything set up earlier. I use MacPorts to install all my dev stuff and it all works mostly fine. But for one thing…

Why do they do this???

In all its infinite wisdom, Apple has chosen to ignore the standard Unix/Linux standard of using /home as the location of user’s home directories, instead opting for /Users. Think Different, I guess. In general, I’ve mostly gotten around this by using the ~ shortcut in scripts, or $HOME. This will go to /home/keith on Linux and /Users/keith on Mac.

But there’s one place I can’t do that. In my Go projects, I set up a workspace that links to local copies of my personal libraries. For this I need to give the go.work file a path to those libraries. Normally it’s like this:


Not the best setup in the world, but this lets me add new functions to my libraries on the fly as I’m developing a particular project. They’ll then be usable in other projects.

Sadly, you cannot use ~ or $HOME here. So every project I want to build on my Mac, I’d have to go in and change the path to /Users/... and then when I get my Thinkpad back, I’d have to go change them back. No thanks.


Some of the stuff I’m going to describe in the next two sections is potentially dangerous to your Mac’s configuration. That said, I’m not deleting anything, just commenting out one line in a file and adding one line in another file. Easily revertible. But do your own research and make up your own mind as to the safety of this.

Easy fix?

My brilliant mind said, “Just create a /home symlink that points to /Users.”

In the end, that’s what I did, and it works great! But there were a couple of hoops to jump through first.

First, oddly enough /home DOES exist on a Mac. It may be hidden. But it’s there and you can’t replace it. It points to /System/Volumes/Data/home. It’s probably empty. But if you try to delete it or unlink it, it won’t let you.

Apparently, this is part of a system designed to auto-mount network volumes. The line that sets it up is in /etc/auto_master. It’s this one:

/home			auto_home	-nobrowse,hidefromfinder

When your Mac boots, it will auto-mount /System/Volumes/Data/home to /home. You can disable this by commenting out this line (you’ll have to do this with sudo of course):

#/home			auto_home	-nobrowse,hidefromfinder

To be perfectly honest with you, I don’t know for certain what side effects this might have. But from everything I’ve read, if you’re not mounting network volumes, you should be OK. I’m not and so far, so good. Worst case, uncomment the line and you’re back to normal.

Reboot your Mac and that /home symlink will be gone.

OK, now it’s an easy fix, right? … right???

Yeah, so now we just do ln -s /Users /home right? Simple.

Nah. It’s gonna tell you you can’t do this on a read-only file system. OK. Workaround, please?

Yes, one workaround coming right up!

You create root symlinks using a special file, /etc/synthetic.conf. Of course! Why not? That file probably won’t exist, unless you’ve done this before, so just create it (using sudo) and add this line:

home	Users

Super important guidelines for this:

  1. No leading / character. It’s assumed.
  2. The whitespace in between home and Users has to be a single TAB character. Not a space or multiple spaces or any other whitespace characters or anything else.

If you mess this up, you may wind up in a boot loop, at which point you’ll have to do some kind of recovery mode nonsense. So look this up and have the instructions on hand in case you need to do that. I was lucky enough to not mess it up the first time.


Everything works fine! All my projects that link to /home/keith/... now work on the Mac. And these projects will continue to work on Linux as well, with no changes needed for either system. I’m happy.

But again, do this at your own risk and have a revert and recovery plan before you start messing with this stuff. I’m using this for a very niche use case. There may be a better solution for this, but I couldn’t figure one out. In 99.99% of other cases, I’d recommend using $HOME or ~ to point to your home directory.

That all said, it’s pretty cool to be able to do this!


While the above worked great, it still felt pretty hacky. After much thought, I came up with another way.

Rather than relying on the actual path to my libraries, I created a symlink in the root directory that pointed to the library folder.

# On Mac via synthetic.conf:
/bitlib -> /Users/keith/Code/golang/libs

# On Linux via ln -s:
/bitlib -> /home/keith/Code/golang/libs

Now in my go.work file I can point to:


This is way more portable and only requires a one-time set up on any given machine. I reverted the changes I made above and I’m going with this solution for now. I’ll leave the post up in case it helps someone with some future problem though.

« Previous Post
Next Post »

Comments? Best way to shout at me is on Mastodon

Or share this post directly on Mastodon