How to Create Symbolic Links in Ubuntu Linux

Symbolic links (symlinks) create lightweight pointers to files and directories, giving you fast shortcuts without duplicating data, similar to how Windows shortcuts reference programs without copying them. They streamline file management, surface configuration files where you need them, and keep projects tidy across disks and mount points. Combined with foundational tasks like moving files and directories, symlinks make it easy to reorganize complex trees without extra copies.

This guide covers creating symlinks with ln, choosing between relative and absolute targets, safely updating or removing existing links, mirroring a directory tree with symlinked files, and troubleshooting with readlink and find. The examples focus on practical Ubuntu usage that transfers well to other Debian-based systems.

What Are Symbolic Links in Linux?

Symbolic links act as pointers to files or directories rather than storing the actual data. Unlike hard links, which directly reference file data at the inode level (an inode is the filesystem record that tracks a file’s metadata), symlinks only reference the file path. If the original file is moved or deleted, the symlink becomes broken.

Symbolic Links vs Hard Links

Understanding the difference helps you choose the right link type for your situation:

• Symbolic links store a path to the target. They work across filesystems and can point to directories, but break if the target moves or is deleted.
• Hard links share the same inode as the original file. They only work within the same filesystem and cannot link to directories, but remain valid even if the original filename is deleted (since both names point to the same data).

For most use cases involving shortcuts, configuration management, and cross-filesystem links, symbolic links are the appropriate choice.

Key Benefits of Using Symbolic Links

• Simplifies file access by creating quick shortcuts to deeply nested directories or frequently used files
• Centralizes configuration management by linking configuration files instead of copying them across multiple locations
• Works across different filesystems unlike hard links, symbolic links can point to files stored on different partitions or external storage devices
• Improves script management by linking scripts or binaries to commonly accessed directories such as /usr/local/bin, allowing execution from any location

Create Symbolic Links on Ubuntu

The ln command creates symbolic links in Ubuntu. To ensure you create symbolic links rather than hard links, include the -s option with the command.

Basic Syntax

ln -s [target] [symlink_name]

• [target] refers to the original file or directory the symlink will point to
• [symlink_name] is the name of the symbolic link being created

Common ln Options Explained

The ln utility ships with the GNU coreutils package on Ubuntu and includes several helpful switches. Understanding what each option does prevents accidental overwrites and hard-to-trace mistakes.

Option	What it does	When to use it
-s	Creates a symbolic link instead of a hard link.	Always include this flag when you need a symlink.
-f	Removes an existing destination before creating the new link.	Safe way to update links without manual cleanup.
-n	Treats the destination as a normal file, even if it is a directory symlink.	Prevents ln from following an existing directory symlink.
-T	Forces ln to treat the link name as a file, not a directory.	Helpful when the destination path might already exist as a directory.
-v	Prints verbose output as the link is created.	Use during troubleshooting to confirm results.

Example: Creating a Symlink to a File

Create a symlink in your home directory pointing to the Nginx configuration file:

ln -s /etc/nginx/nginx.conf ~/nginx.conf

This creates a symlink in the home directory pointing to the actual Nginx configuration file. Instead of navigating to /etc/nginx/nginx.conf, you can access it quickly using ~/nginx.conf.

Verify a Newly Created Symlink

Confirm the link worked as expected before relying on it in scripts. A quick ls -l reveals the arrow (->) that shows the target, while readlink resolves the final destination:

ls -l ~/nginx.conf

Expected output showing the symlink and its target:

lrwxrwxrwx 1 user user 21 Jan 27 10:00 /home/user/nginx.conf -> /etc/nginx/nginx.conf

The l at the beginning indicates a symbolic link, and the arrow (->) shows the target path. Use readlink -f to resolve the full absolute path:

readlink -f ~/nginx.conf

/etc/nginx/nginx.conf

If the output does not point where you expect, recreate the link with the correct path or use the -f flag to replace it safely.

Creating Symbolic Links for Directories

Symlinks can also point to directories, making navigation simpler. This is particularly useful for web development, where project directories often live in deeply nested paths.

Example: Creating a Symlink to a Directory

ln -s /var/www/html ~/website

After creating this symlink, you can access the directory /var/www/html using ~/website, reducing the need for long paths. Verify the directory symlink:

ls -ld ~/website

lrwxrwxrwx 1 user user 13 Jan 27 10:05 /home/user/website -> /var/www/html

The -d flag ensures ls shows information about the symlink itself rather than listing the contents of the target directory. You can now cd ~/website to navigate directly to the web root.

Removing Symbolic Links

Since symbolic links do not contain actual data, deleting them does not affect the original file or directory. The target remains intact.

Deleting a Symlink with rm

The standard rm command removes symlinks just like regular files:

rm ~/nginx.conf

When removing a symlink to a directory, do not include a trailing slash. Running rm ~/website/ (with the slash) may attempt to delete the contents of the target directory instead of the link itself. Always use rm ~/website (without the trailing slash) to remove just the symlink.

Deleting a Symlink with unlink

The unlink command is an alternative that explicitly removes a single file or symlink:

unlink ~/nginx.conf

This method is useful when you want to ensure only the link is removed. Unlike rm, unlink does not accept multiple arguments or recursive flags, making it a safer choice for removing individual symlinks.

Update or Replace Existing Symbolic Links

Symlinks do not support in-place edits; you replace the link with a new one. The most direct method combines -s (symbolic) and -f (force), which removes any existing link path before creating the new one:

ln -sf /new/path/file.txt /path/to/symlink

If you prefer an explicit two-step process, delete the old link and create a new one:

rm /path/to/symlink
ln -s /new/path/file.txt /path/to/symlink

Verify the updated symlink points to the new target:

readlink -f /path/to/symlink

Advanced Use Cases for Symbolic Links

Symbolic links are commonly used in system administration and software management. Here are some advanced use cases demonstrating their real-world benefits.

Linking Executables for Global Access

If you manually install software outside system directories, creating a symlink in /usr/local/bin/ allows you to run the program from any location. Because that directory is writable only by root on Ubuntu, prepend sudo when creating the link:

sudo ln -s /opt/customapp/custombinary /usr/local/bin/customapp

This allows you to run customapp from anywhere in the terminal rather than specifying the full path each time. Verify the symlink was created correctly:

ls -l /usr/local/bin/customapp

lrwxrwxrwx 1 root root 27 Jan 27 10:15 /usr/local/bin/customapp -> /opt/customapp/custombinary

Ensure the target binary is executable; otherwise, the symlink will not run. You can set the executable bit with chmod:

chmod +x /opt/customapp/custombinary

Organizing Dotfiles and Shared Configurations

Many developers track dotfiles in a Git repository and link them into place. Symlinks make it easy to keep version-controlled copies under ~/dotfiles while exposing them in the locations applications expect:

ln -sfn ~/dotfiles/.bashrc ~/.bashrc
ln -sfn ~/dotfiles/.config/nvim ~/.config/nvim

The -sfn combination forces an overwrite (-f), creates a symbolic link (-s), and prevents ln from traversing existing directory symlinks (-n). This protects nested configuration trees from being merged unexpectedly.

Linking to Network Shares

Symlinks provide quick access to mounted network directories, saving time navigating long paths:

ln -s /mnt/server/share ~/network_drive

This allows instant access to the network share by using ~/network_drive. Keep in mind that if the network share is not mounted, the symlink will appear broken until the mount is restored.

Creating Relative Symbolic Links

Relative symlinks are useful when working with files that are likely to be moved together, such as project directories in version control:

ln -s ../shared/resources project-resources

This ensures project-resources always points to ../shared/resources, even if the directory structure is moved to a different location. See the “Relative vs. Absolute Symlinks” section below for detailed guidance on when to use each type.

Replicating a Directory Structure with Symbolic Links for Files

While the ln command does not create a single “recursive” symlink that dynamically reflects all contents of a target directory, you can use find in combination with mkdir and ln to create a mirrored directory structure where symlinks represent all original files in the new structure. This approach proves useful for creating a linked copy of a complex directory tree.

To replicate the structure of /original/directory under /symlink/directory, with all files in the replicated structure being symlinks to their originals:

cd /original/directory
# First, create the same directory structure in the target location
find . -type d -exec sh -c 'mkdir -p "/symlink/directory/$1"' _ {} \;
# Then, create symlinks for all files into the new structure
find . -type f -exec sh -c 'ln -s "$(pwd)/$1" "/symlink/directory/$1"' _ {} \;

This method first creates all necessary subdirectories in /symlink/directory and then populates them with symlinks pointing back to the files in /original/directory. The shell wrapper (sh -c) ensures paths with spaces or special characters receive correct handling. The symlinks use absolute paths to the original files, making them more robust if you move /symlink/directory (though the links would still break if you move /original/directory or files within it). Ensure /symlink/directory exists before running these commands or that the user running them has permission to create it and its subdirectories.

This mirrors only regular files (existing symlinks inside the source tree are skipped). If a destination path already exists, ln will fail unless you deliberately use -f. Absolute targets make the mirror portable when moving /symlink/directory but will break if you later move /original/directory. Creating correct relative symlinks is possible but requires computing a per-file relative path (for example, with realpath --relative-to). For background on using find -exec, see this guide.

Troubleshooting Symbolic Links

Why Is My Symlink Broken?

A broken symlink occurs when someone moves, renames, or deletes the target file or directory it points to. Broken symlinks still exist in the filesystem but point to nothing. To find all broken symlinks within a specific directory and its subdirectories:

find /path/to/check -xtype l

The -xtype l test matches symlinks whose target does not exist. Example output showing broken links:

/path/to/check/old_config
/path/to/check/projects/dead_link

To audit broken links and see which targets they reference, list them with their stored paths before cleanup:

find /path/to/check -xtype l -printf '%p -> %l\n'

/path/to/check/old_config -> /etc/app/config.old
/path/to/check/projects/dead_link -> /home/user/deleted_project

Once you have confirmed which links are safe to remove, delete all broken symlinks recursively:

find /path/to/check -xtype l -delete

How Can I List All Symbolic Links in a Directory?

To display symbolic links located directly within the current directory (or a specified directory), use find with a shallow depth limit so hidden entries and locale-specific ls output remain visible:

find . -maxdepth 1 -type l -exec ls -l {} +

Example output showing symlinks in the current directory:

lrwxrwxrwx 1 user user 21 Jan 27 10:00 ./nginx.conf -> /etc/nginx/nginx.conf
lrwxrwxrwx 1 user user 13 Jan 27 10:05 ./website -> /var/www/html

This lists every symlink in the current directory, including dotfiles, without issues from color codes or locale differences.

To find all symbolic links recursively within a directory and its subdirectories:

find /path/to/your_directory -type l

Replace /path/to/your_directory with the actual directory path. This command lists all files of type l (symlink) within that path.

How to Check a Symlink Target

To see where a symbolic link points, use the readlink command. This is especially useful for troubleshooting or verifying symlink targets:

readlink /path/to/symlink

This prints the stored target path exactly as recorded in the symlink. For the full resolved absolute path (following any chained symlinks), use the -f flag:

readlink -f /path/to/symlink

/etc/nginx/nginx.conf

The -f option resolves through chained links to the final target. If any element in the chain is missing, resolution stops at the deepest existing path, which helps identify where the break occurred.

For more details, see the official ln man page.

Note on Permissions

When creating symbolic links in system directories such as /usr/local/bin or /etc, you need to use sudo to gain the necessary permissions:

sudo ln -s /opt/customapp/custombinary /usr/local/bin/customapp

Always use caution when running commands with sudo. Double-check your paths before pressing Enter.

On Linux, a symlink’s own permission bits are typically ignored; access checks evaluate the target’s ownership and mode. In practice, the link’s permissions rarely matter; the target’s permissions determine whether operations succeed. You may notice symlinks always show lrwxrwxrwx (777) permissions in ls -l output, but this is cosmetic since the actual access control comes from the target file.

Quoting Paths with Spaces

If your file or directory names contain spaces, enclose the paths in straight quotes to avoid errors. When referring to your home directory, use $HOME (which expands safely inside quotes) or leave the tilde unquoted:

ln -s "/path/with spaces/original file.txt" "$HOME/link name.txt"

Alternatively, escape spaces with backslashes if you prefer not to use quotes:

ln -s /path/with\ spaces/original\ file.txt ~/link\ name.txt

Relative vs. Absolute Symlinks

Symbolic links can use either absolute or relative paths for their targets. Choosing the right type depends on how you plan to use and potentially move your files.

Relative symlinks prove useful when you expect to move a project or directory tree as a unit (such as in version-controlled repositories), since the links remain valid as long as you preserve the relative structure. They specify the target path relative to the location of the symlink itself:

# Assume your current directory is /home/user/project
# The target file is /home/user/shared/config.txt
# Create a relative symlink in /home/user/project
ln -s ../shared/config.txt project_config

In this example, project_config in /home/user/project points to /home/user/project/../shared/config.txt, which resolves to /home/user/shared/config.txt. If you move the project and shared directories together to another location (e.g., /new/location/user/project and /new/location/user/shared), the relative link remains valid.

Absolute symlinks work best when the target location stays fixed or you share it across different locations, as they always point to the same absolute path regardless of where you move the symlink. They specify the full path from the root directory (/):

# The target file is always /etc/nginx/nginx.conf
# Create an absolute symlink in your home directory
ln -s /etc/nginx/nginx.conf ~/nginx.conf

In this case, ~/nginx.conf will always point directly to /etc/nginx/nginx.conf, regardless of your current location or if you move your home directory. Absolute links will break if the target file or directory’s absolute path changes.

Choose the type that best fits your workflow and how you expect to move or share your files.

Best Practices for Managing Symlinks

• Prefer relative paths inside project directories so clones or backups stay portable.
• Keep naming predictable: mirror the original filename to make broken links easier to diagnose.
• Document custom links in provisioning scripts or README files to avoid surprises for collaborators.
• Audit regularly with find -xtype l on shared servers (or print mappings with -printf '%p -> %l') so stale links do not accumulate.
• Test with non-root accounts before relying on symlinks in production automation, especially when sudo is required.
• Avoid trailing slashes when removing directory symlinks to prevent accidentally deleting target contents.

Conclusion

Symlinks provide fast, flexible access to files and directories without duplication. With ln, you can create links, safely update or replace them, and choose relative or absolute targets for portability. Troubleshooting with readlink and find keeps targets accurate, while small practices such as predictable names, executable binaries in /usr/local/bin, and periodic audits help maintain a clean, reliable filesystem.