Relative Symlink on Mac: No ln -r, and -f Mutes -w

The GNU way to make a relative symlink is one flag: ln -sr data/config.txt bin/ works out that the link in bin/ should say ../data/config.txt and writes that. On a Mac, the same line stops before it does anything:

$ ln -sr data/config.txt bin/
ln: illegal option -- r
usage: ln [-s [-F] | -L | -P] [-f | -i] [-hnv] source_file [target_file]
       ln [-s [-F] | -L | -P] [-f | -i] [-hnv] source_file ... target_dir
$ echo $?
1

That failure is the harmless one. The usual fix is to drop the r, and ln -s data/config.txt bin/ exits 0 and leaves a link that points nowhere. I ran the whole set on this Mac mini (macOS 26.4.1) against gln from GNU coreutils 9.12, read Apple's ln.c, and counted the 31,189 symlinks Homebrew has made on this machine to see how a tool that gets it right does it. Here's what macOS ln does with a relative path, the one flag it has that GNU doesn't, and a small function that gives you -r without installing anything.

The path is read from the link's folder, not yours

ln -s doesn't check or rewrite the path you give it. It stores the string as-is, and the system resolves it later, starting from the directory the link is in. Where you were standing when you ran ln doesn't matter. An answer on Unix & Linux Stack Exchange says it directly: a relative target "resolves relatively to the link name, not your current working directory." GNU's ln manual says the same thing and adds that "many users prefer to first change directories" before making one. -r exists so that you don't have to.

Here is the left-hand case as it happened:

$ ln -s data/config.txt bin/config.txt; echo "exit $?"
exit 0
$ readlink bin/config.txt
data/config.txt
$ cat bin/config.txt
cat: bin/config.txt: No such file or directory

One belief to drop while you're here. An answer in an Apple Community thread says the shell expands an unquoted ../ path into an absolute one, so you have to quote it. I didn't see that. Unquoted ln -s ../data/config.txt bin/config.txt stored ../data/config.txt exactly, in zsh and bash alike. Shells expand ~ and globs, not ...

macOS ln has a check GNU doesn't: -w

The macOS man page lists -w: "Warn if the source of a symbolic link does not currently exist." The usage line doesn't show it, which is why few people know it's there. Apple's ln.c does the check properly: for a relative target, it joins the string to the link's directory and calls stat() on that, so it catches exactly the mistake above.

$ ln -sw data/config.txt bin/config.txt
ln: warning: data/config.txt: No such file or directory
$ echo $?
0
$ ls -l bin/config.txt
lrwxr-xr-x@ 1 sg-mini  wheel  15 Oct  3 10:36 bin/config.txt -> data/config.txt

Two limits. First, it's only a warning. The exit status is 0 and the broken link is made anyway, so set -e won't stop on it. If you need a script to fail, test the link afterwards with [ -e "$link" ], which follows the link and is false when the target is missing. Second, -f turns it off. In ln.c, case 'f' sets wflag = false, and -F does the same. The man page puts it as "-f overrides any previous -i and -w options", so the order of the letters decides whether you get the check:

Command (target missing)	Warning?	Exit
ln -sw nope bin/t	yes	0
ln -swf nope bin/t	no	0
ln -sfw nope bin/t	yes	0
ln -swF nope bin/t	no	0
ln -swi nope bin/t	yes	0

Since most scripts use ln -sf, the habit to build is ln -sfw with the w last. gln -sr has no equivalent: pointing it at a missing file printed nothing, exited 0, and made ../data/nope.txt. The FreeBSD ln(1) page marks -w as non-standard, so it's for your Mac, not for portable scripts.

The -sf trap when the old link points to a folder

This one isn't new, but I hit it while testing, so it goes in. If cur is a symlink to a directory and you try to repoint it with -sf, ln follows cur into the directory and makes the new link inside it:

$ ln -s data cur
$ ln -sf v2 cur; echo "exit $?"
exit 0
$ readlink cur
data
$ ls -l data/v2
lrwxr-xr-x@ 1 sg-mini  wheel  2 Oct  3 10:36 data/v2 -> v2

cur didn't change, and there's now a link at data/v2 that points to itself. ln -sfh v2 cur (or -sfn, which macOS takes for compatibility) replaces cur as intended. GNU uses -n for the same thing.

How Homebrew does it: 31,094 of 31,189

Homebrew is the biggest maker of symlinks on most Macs, so I counted. /opt/homebrew on this machine (Homebrew 7.0.7) has 31,189 symlinks. 31,094 of them (99.7%) are relative, 95 are absolute, and none are broken. The relative ones go up to nine ../ levels deep. Most of the 95 absolute ones are under share/, plus a few cask commands in bin/, such as gcloud and slack, that point into Caskroom.

Homebrew doesn't call ln at all. Its make_relative_symlink is three lines of Ruby: create the folder, compute src.relative_path_from(dirname), and call File.symlink with the result. Ruby itself later added FileUtils.ln_sr for the same job (Feature #18925, 2022). Work out the path from the link's directory first, then hand ln a string that's already right. That's the approach to copy.

A drop-in for ln -sr, using what ships with macOS

/bin/realpath on macOS takes only -q. --relative-to, -s and -m all fail with illegal option, so the popular answer on converting absolute symlinks to relative, which uses realpath --relative-to, doesn't run here. Perl does ship with macOS (5.34.1 on this machine) and has File::Spec->abs2rel:

# lnr TARGET LINK_OR_DIR: like GNU ln -sr, with macOS ln's -w check
lnr() {
  local t=$1 l=$2 td ld
  [ -d "$l" ] && [ ! -L "$l" ] && l="$l/$(basename "$t")"
  td=$(cd -P "$(dirname "$t")" && pwd -P) || return 1
  ld=$(cd -P "$(dirname "$l")" && pwd -P) || return 1
  ln -sw "$(perl -MFile::Spec -e 'print File::Spec->abs2rel($ARGV[0], $ARGV[1])' \
    "$td/$(basename "$t")" "$ld")" "$l"
}

The cd -P / pwd -P lines matter, and I only found out why by testing. Without them, I got two kinds of wrong result:

• The link's folder is itself a symlink. With alias -> real/sub, both abs2rel and Python's os.path.relpath("data/config.txt", "alias") return ../data/config.txt. The system resolves that from real/sub, where it doesn't exist. gln -sr and lnr both return ../../data/config.txt, which works. The top answer to the Python relative-symlink question uses os.path.relpath directly, so it has this problem too.
• Mixed /tmp and /private/tmp. On macOS, /tmp is a symlink. Pass one path of each kind and the naive calculation returns ../../../../private/tmp/lnlab2/data/config.txt. That works, but only because /tmp exists. The canonical version is ../data/config.txt.

I ran lnr on the cases in this post: a file into a folder, the symlinked folder, the mixed /tmp paths, and a missing target. The first three produced the same string gln -sr did. The missing target got the -w warning, which gln doesn't give. One difference remains. lnr needs the target's directory to exist (cd -P fails if it doesn't), and gln -r doesn't. If you'd rather have GNU, brew install coreutils gives you gln. Plain ln stays BSD, the same as with stat on a Mac and head's illegal line count.

When a relative link is the right choice

Use a relative link when the link and its target move together: inside a repo, a release folder, or a backup copy. I checked by moving a test folder. The relative link still read hi, and the absolute one broke. The simplest case needs no calculation. A link to a file in the same folder, like the ln -s AGENTS.md CLAUDE.md pattern from the AGENTS.md vs CLAUDE.md post, is relative by default. Use an absolute link when the target is fixed and the link moves. Claude Code's ~/.claude/debug/latest on this machine is absolute, which makes sense for a pointer into one fixed folder. If you're syncing either kind to another machine, check how your copy tool handles links first. The rsync that ships with macOS isn't the one most guides assume.

Sources: every command and output above was run on 2026-10-03 on a Mac mini (macOS 26.4.1) in throwaway folders under /tmp, using /bin/ln, /bin/realpath, and gln from GNU coreutils 9.12 (Homebrew). The -f and -w behavior is from Apple's file_cmds-479 ln.c, and each row of the table was run, not inferred. The Homebrew numbers come from find /opt/homebrew -type l and os.readlink on each result. "Broken" means os.path.exists was false. The Homebrew method is from reading pathname.rb at the commit linked above. I didn't test FreeBSD or Linux directly. GNU behavior here is gln on macOS.