← Full reference

ln

Hard and symbolic links to files and directories

ln creates links. A symbolic link (ln -s) is a small file that stores the path to its target, like a shortcut. A hard link (ln without options) is another name for the same file: both names share one inode and the same contents.

Syntax

ln -s target link_name        # symbolic
ln target link_name           # hard
ln -s target… directory/         # links with the same names inside a directory
ln -s -t directory target…       # same, with the directory given first

The order is the same as for cp: first what you're linking to, then what you're creating. If no link name is given, the link appears in the current directory with the target's name.

Link type

OptionWhat it does
(no options)hard link
-ssymbolic link
-rstore a path relative to the link's directory in the symbolic link (together with -s)
-L / -Pa hard link to a symbolic link: to its target / to the link itself (default -P)

If the name is already taken

OptionWhat it does
(default)error "File exists"
-fremove the existing file or link and create it anew
-iask before replacing
-bkeep the replaced file with a ~ suffix; --backup=numbered — .~1~, .~2~…
-nif the name is a link to a directory, treat it as a file and replace the link itself
-Ttreat the link name as a regular file even if it's a directory: a real directory won't be overwritten

Other options

OptionWhat it does
-t directorycreate links in this directory (handy with xargs)
-vprint each link created

Symbolic or hard

SymbolicHard
To a directorypossiblenot possible
To another filesystempossiblenot possible ("Invalid cross-device link")
Target deletedthe link "dangles" and can't be openedthe data lives on while at least one name remains
Target movedthe link breaksdoesn't matter, it's the same name
How to spot itls -l shows name -> target, type lthe same inode in ls -li, link count greater than 1

Inspecting links

CommandWhat it shows
ls -llrwxrwxrwx … name -> target; for files the second field is the number of hard links
ls -lithe inode number in the first column
readlink linkthe path stored in the link, as is
readlink -f link / realpaththe final absolute path after resolving all links
readlink -e linkthe same, but an error (code 1) if the target doesn't exist
stat -c '%N %h %i' filelink and target / number of hard links / inode
namei -l patheach path component with permissions — exactly where a chain of links breaks

Examples

# a symbolic link to a config
ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/

# switch a link to another version of a directory
ln -sfn /srv/app/releases/v2 /srv/app/current

# a relative link: the path is computed from the link's location
ln -sr /srv/app/shared/config.yml /srv/app/current/config.yml

# where a link points: as stored and the final path
readlink /srv/app/current
readlink -f /srv/app/current

# links to several programs in a directory
ln -s -t /usr/local/bin /opt/tool/bin/tool /opt/tool/bin/tool-cli

# replace a file with a link, keeping the old one as config.yml~
ln -sfb /srv/app/shared/config.yml config.yml

# a hard link and a check: one inode, link count 2
ln data.csv data-copy.csv
ls -li data.csv data-copy.csv

# find "dangling" links
find /etc -xtype l

# find all names of one file
find / -xdev -samefile data.csv 2>/dev/null

Pitfalls

  • A relative path is resolved from the link's directory, not the current one. ln -s config.yml /srv/app/current/config.yml creates a link to /srv/app/current/config.yml — to itself ("Too many levels of symbolic links"). Write an absolute path or use -r.
  • ln -sf over a link to a directory doesn't replace it but creates a new link inside the target directory. To switch, always write -sfn.
  • -f won't replace a real directory: "cannot overwrite directory". With -T the command also refuses — that's a safeguard.
  • Without -f an existing name isn't overwritten: "File exists".
  • A dangling link looks normal in ls -l, but can't be opened: "No such file or directory". Check: test -e link is false, test -L link is true.
  • A symbolic link's permissions are always lrwxrwxrwx and don't matter — the target's permissions are checked.
  • A hard link isn't a copy. Changes through one name are visible through the other. And an editor that saves a file by "write a new one and rename" breaks this connection.
  • A hard link to a symbolic link copies the link itself by default (-P), not the file. To link to the file itself, add -L.

See also

find · stat · ls · cp · mv · chmod · tar