VMware ESXi and vSphere Cluster Management

Symbolic Links in Linux: Creating, Inspecting, and Managing Symlinks

Learn how Linux symbolic links work, how they differ from hard links, and how to create, inspect, repair, and safely remove symlinks with ln.

A symbolic link, also called a symlink or soft link, is a special filesystem object that refers to another pathname. It provides an alternate name or location for a file or directory.

When a program opens a working symlink, Linux normally follows the stored path automatically and accesses the referenced target. The symlink is still a separate filesystem entry: it does not contain a copy of the target's data.

Key Terms

  • Target: The file, directory, or pathname referenced by a symlink.
  • Link name: The pathname created for the symlink itself.
  • Inode: A filesystem metadata record associated with a file object. A symlink and its target have different inodes.
  • Dangling or broken symlink: A symlink whose referenced pathname cannot currently be resolved.
  • Absolute path: A path beginning at the filesystem root, such as /srv/app/config.conf.
  • Relative path: A path interpreted from a particular location, such as ../shared/config.conf.

Why Use Symbolic Links?

Symlinks are useful when one file or directory should be reachable through more than one pathname. Common uses include providing a convenient command or configuration name, exposing a shared project directory, and switching between versions of software without changing every consumer's path.

For example, an application can always use /srv/app/current while that symlink is changed to point to a newer release directory. The application path remains stable even though the release directory changes.

Symbolic Links Compared with Hard Links

A hard link is another directory entry for the same inode as an existing file. A symlink instead has its own inode and stores a pathname that the filesystem resolves.

Property: Own inode versus shared inode

Symbolic link: Has its own inode.

Hard link: Shares the target file's inode.

Property: What it references

Symbolic link: References a pathname.

Hard link: Refers directly to the same filesystem object and inode.

Property: Cross-filesystem support

Symbolic link: Can point across filesystems, partitions, and mount points.

Hard link: Normally must be on the same filesystem because the inode is local to that filesystem.

Property: Directory-link behavior

Symbolic link: Can point to directories.

Hard link: Directory hard links are generally disallowed for ordinary users and are restricted to protect filesystem structure.

Property: Effect of target deletion

Symbolic link: Remains as a dangling link when its target pathname disappears.

Hard link: The inode and data remain accessible through the hard link. The data is removed only after all hard links and open references are gone.

Property: Typical use cases

Symbolic link: Alternate paths, directory aliases, version switching, and cross-filesystem references.

Hard link: Multiple names for the same regular file on one filesystem.

Creating a Symbolic Link with ln -s

The ln command creates links. Its -s option requests a symbolic link. The order is important:

ln -s TARGET LINK_NAME

The first path is the target to store in the link. The second path is the name of the symlink that will be created.

Link to a Regular File

mkdir -p ~/symlink-lab
printf 'first version
' > ~/symlink-lab/original.txt
ln -s ~/symlink-lab/original.txt ~/symlink-lab/shortcut.txt
ls -l ~/symlink-lab/shortcut.txt
cat ~/symlink-lab/shortcut.txt

The ls -l output identifies the entry as a symlink and normally displays an arrow, for example:

shortcut.txt -> /home/user/symlink-lab/original.txt

cat follows the working link and prints the target's current content. Choose link names that describe their purpose, and place them where users or applications expect to find them.

Link to a Directory

mkdir -p ~/symlink-lab/project-data
printf 'report
' > ~/symlink-lab/project-data/report.txt
ln -s ~/symlink-lab/project-data ~/symlink-lab/data
ls ~/symlink-lab/data
cd ~/symlink-lab/data

The data entry is a symlink, but commands can use it as a directory path because the link resolves to project-data.

Inspecting and Verifying Symlinks

Use ls -l

ls -l LINK_NAME

A symbolic link is shown with an l at the beginning of its mode display and an arrow to the stored destination:

lrwxrwxrwx 1 user user 31 Aug 19 10:00 shortcut.txt -> /home/user/symlink-lab/original.txt

The permission-looking characters on a symlink are not the permissions that determine access to the target. Access is controlled by the target and the directories leading to it.

Compare Inodes with ls -li

ls -li ~/symlink-lab/original.txt ~/symlink-lab/shortcut.txt

The two entries should show different inode numbers. The target has its own inode, and the symlink has another inode containing link metadata and the stored pathname.

For contrast, a hard link can be created for a regular file with:

ln ~/symlink-lab/original.txt ~/symlink-lab/hard-name
ls -li ~/symlink-lab/original.txt ~/symlink-lab/hard-name

The original file and hard-name normally show the same inode number.

Use readlink and stat

readlink LINK_NAME
readlink -f LINK_NAME
stat TARGET LINK_NAME

readlink prints the pathname stored directly in the symlink. readlink -f resolves the link to a canonical path when the destination can be resolved. stat displays detailed metadata; use it to inspect the link and target separately.

What Happens When the Target Changes?

A symlink follows a pathname; it does not preserve a copied snapshot of the target's content.

printf 'updated version
' > ~/symlink-lab/original.txt
cat ~/symlink-lab/shortcut.txt

Reading through shortcut.txt now shows the updated target content. Editing the target changes what users observe through the symlink.

If the target is removed or moved, the symlink itself remains:

rm ~/symlink-lab/original.txt
ls -l ~/symlink-lab/shortcut.txt
readlink ~/symlink-lab/shortcut.txt
cat ~/symlink-lab/shortcut.txt

The link is now dangling or broken. It still stores the old pathname, but that pathname no longer identifies a usable destination. Recreating a file or directory at the exact referenced path can make the previously broken link work again.

printf 'restored target
' > ~/symlink-lab/original.txt
cat ~/symlink-lab/shortcut.txt

Absolute and Relative Symbolic Links

An absolute symlink stores a path beginning at the filesystem root:

ln -s /srv/app/config/settings.conf ~/settings.conf

This is clear and appropriate for stable system locations. However, moving the directory tree or changing the system layout can invalidate the link because the absolute pathname remains unchanged.

A relative symlink stores a path interpreted relative to the directory containing the symlink, not relative to the shell's current working directory:

ln -s ../shared/config.conf config.conf

If config.conf is in project/service/, Linux resolves ../shared/config.conf from project/service/. This makes relative links useful for relocatable project layouts.

Link type: Absolute symlink

Stored target form: Begins at the root, such as /srv/app/config/settings.conf.

Best use case: Stable system paths and locations that should not depend on the link's parent directory.

Move or rename consideration: Moving the containing tree usually does not change the stored path, so the link may point to the old location.

Link type: Relative symlink

Stored target form: Resolved from the symlink's containing directory, such as ../shared/config.conf.

Best use case: Project trees and application bundles that should move as one unit.

Move or rename consideration: Moving the complete tree can preserve the link, but moving only the link or target may break the relative relationship.

Build Relative Paths from the Link's Location

A frequent mistake is calculating a relative target from the directory where ln is run. Instead, calculate it from the directory that will contain the link.

mkdir -p ~/symlink-lab/project/service ~/symlink-lab/project/shared
printf 'shared settings
' > ~/symlink-lab/project/shared/config.conf
cd ~/symlink-lab/project/service
ln -s ../shared/config.conf config.conf
cat config.conf
mv ~/symlink-lab/project ~/symlink-lab/project-moved
cat ~/symlink-lab/project-moved/service/config.conf

The relative link can continue to work after the entire project directory is moved because the same relative relationship is preserved.

Removing Symbolic Links Safely

Use rm with the link name to remove the symlink itself:

rm LINK_NAME

This does not intentionally remove the target. It is important to name the symlink, not the path obtained by following it.

Take special care with directory symlinks. Remove the link without a trailing slash:

rm data

A trailing slash can cause a command or utility to treat the operand as the referenced directory. Avoid recursive removal such as rm -r unless you have verified exactly what the command will operate on. Always inspect the entry first:

ls -ld data

Deleting a symlink is different from deleting the directory or file to which it points. If the target itself is meant to be removed, identify and remove that target explicitly.

Overwrite and Replacement Options

If the link name already exists, ln may refuse to create the new link. Inspect the destination before changing it:

ls -ld LINK_NAME
  • -f forces removal of an existing destination in situations supported by the implementation.
  • -i asks for confirmation before replacing an existing destination.
  • -n prevents some implementations from following an existing symlink to a directory when treating the destination.
  • -v requests verbose output where supported.

A commonly used replacement command is:

ln -sfn TARGET LINK_NAME

Use it cautiously. Verify both paths first, because forceful replacement can remove an unintended existing link or destination.

Permissions and Application Behavior

A symlink does not bypass permissions. The user must have suitable permission on the target, and usually execute permission on every parent directory in the target path. Check the relevant entries with:

ls -l TARGET
ls -ld PARENT_DIRECTORY

Applications normally follow symlinks, but a program can deliberately refuse to follow them for security or correctness. Backup tools, archive tools, security scanners, and file-serving applications may offer separate options for copying the link itself or following it to the target.

Useful Symlink Commands

Command: ln -s TARGET LINK_NAME

Purpose: Create a symbolic link to a file or directory.

Example use: ln -s /srv/app/config/settings.conf ~/settings.conf

Command: ls -l LINK_NAME

Purpose: Identify a symlink and display its referenced path.

Example use: ls -l ~/settings.conf

Command: ls -li TARGET LINK_NAME

Purpose: Compare inode numbers.

Example use: ls -li original.txt shortcut.txt

Command: readlink LINK_NAME

Purpose: Print the pathname stored in the symlink.

Example use: readlink shortcut.txt

Command: stat TARGET LINK_NAME

Purpose: Inspect detailed metadata.

Example use: stat original.txt shortcut.txt

Command: rm LINK_NAME

Purpose: Remove the symlink itself.

Example use: rm shortcut.txt

Command: find . -xtype l

Purpose: Find dangling symbolic links below the current directory.

Example use: find ~/project -xtype l

Troubleshooting Symlinks

The Link Exists but Says “No Such File or Directory”

The target may have been deleted, renamed, or moved, or the link may contain an incorrect path.

ls -l LINK_NAME
readlink LINK_NAME
readlink -f LINK_NAME

Check whether the stored target exists. Restore the target at the expected path, or remove and recreate the symlink with the correct path. For a link inside a movable project tree, a correctly calculated relative path may be more suitable.

A Relative Link Fails Immediately

Resolve the relative path from the symlink's parent directory. If the link is project/service/config.conf and stores ../shared/config.conf, the expected target is project/shared/config.conf, not a path calculated from the directory where the command happened to run.

ln Reports That the Destination Exists

A regular file, directory, or previous symlink already occupies the link name.

ls -ld LINK_NAME

Choose another name, remove the unwanted link, or use -i or -f only after verifying the destination.

The Symlink Exists but Access Is Denied

Inspect permissions on the target and each parent directory. Also verify the current user and group memberships. Correct the permissions according to the system's security policy rather than changing permissions broadly.

Removing a Directory Link Behaves Unexpectedly

Check whether the command included a trailing slash or recursive option. Confirm the entry type with ls -ld, then remove the link name without a trailing slash and avoid recursive deletion unless the intended target has been verified.

Practical Checklist

  1. Identify the intended target and link name.
  2. Choose an absolute target for a stable system location or a relative target for a movable directory tree.
  3. Create the link with ln -s TARGET LINK_NAME.
  4. Verify the arrow and destination with ls -l.
  5. Use readlink to inspect the stored pathname.
  6. Use ls -li or stat when inode or metadata details matter.
  7. Remove only the link name with rm LINK_NAME, without a trailing slash for directory links.

For a concise reference, see Symbolic Links.