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
| Option | What it does |
|---|
| (no options) | hard link |
-s | symbolic link |
-r | store a path relative to the link's directory in the symbolic link (together with -s) |
-L / -P | a hard link to a symbolic link: to its target / to the link itself (default -P) |
If the name is already taken
| Option | What it does |
|---|
| (default) | error "File exists" |
-f | remove the existing file or link and create it anew |
-i | ask before replacing |
-b | keep the replaced file with a ~ suffix; --backup=numbered — .~1~, .~2~… |
-n | if the name is a link to a directory, treat it as a file and replace the link itself |
-T | treat the link name as a regular file even if it's a directory: a real directory won't be overwritten |
Other options
| Option | What it does |
|---|
-t directory | create links in this directory (handy with xargs) |
-v | print each link created |
Symbolic or hard
| Symbolic | Hard |
|---|
| To a directory | possible | not possible |
| To another filesystem | possible | not possible ("Invalid cross-device link") |
| Target deleted | the link "dangles" and can't be opened | the data lives on while at least one name remains |
| Target moved | the link breaks | doesn't matter, it's the same name |
| How to spot it | ls -l shows name -> target, type l | the same inode in ls -li, link count greater than 1 |
Inspecting links
| Command | What it shows |
|---|
ls -l | lrwxrwxrwx … name -> target; for files the second field is the number of hard links |
ls -li | the inode number in the first column |
readlink link | the path stored in the link, as is |
readlink -f link / realpath | the final absolute path after resolving all links |
readlink -e link | the same, but an error (code 1) if the target doesn't exist |
stat -c '%N %h %i' file | link and target / number of hard links / inode |
namei -l path | each 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