Python os.readlink Function

Last modified April 11, 2025

This comprehensive guide explores Python’s os.readlink function, which reads the target of symbolic links. We’ll cover path resolution, error handling, and practical filesystem navigation examples.

Basic Definitions

The os.readlink function returns a string representing the path to which the symbolic link points. It only works on symbolic links.

Key parameters: path (symbolic link to read). Returns the link target path. Raises OSError if path isn’t a symbolic link or other errors occur.

Reading a Basic Symbolic Link

The simplest use of os.readlink reads the target of a symbolic link. First we create a link, then read its target.

basic_readlink.py

import os

Create a symbolic link

target = “original.txt” link_name = “symlink.txt”

with open(target, “w”) as f: f.write(“Test content”)

os.symlink(target, link_name)

Read the symbolic link

try: link_target = os.readlink(link_name) print(f"’{link_name}’ points to ‘{link_target}’") except OSError as e: print(f"Error reading link: {e}")

Clean up

os.remove(link_name) os.remove(target)

This example creates a file and symbolic link, then reads the link target. The try/except block handles cases where the path isn’t a symbolic link.

Note that os.readlink returns the raw link contents, which may be relative or absolute depending on how the link was created.

Handling Relative Path Links

Symbolic links can contain relative paths. os.readlink returns the exact stored path without resolution. This example demonstrates handling.

relative_link.py

import os

Create directory structure

os.makedirs(“dir1/dir2”, exist_ok=True) with open(“dir1/file.txt”, “w”) as f: f.write(“Test file”)

Create relative symbolic link

os.chdir(“dir1/dir2”) os.symlink("../file.txt", “rel_link.txt”)

Read the link

link_path = “rel_link.txt” try: target = os.readlink(link_path) print(f"Link points to: {target}")

# Resolve to absolute path
abs_path = os.path.abspath(target)
print(f"Absolute path: {abs_path}")

# Verify the target exists
if os.path.exists(target):
    print("Target exists")
    with open(target) as f:
        print(f.read())
else:
    print("Target doesn't exist")

except OSError as e: print(f"Error: {e}")

Clean up

os.chdir("../..") os.remove(“dir1/dir2/rel_link.txt”) os.remove(“dir1/file.txt”) os.removedirs(“dir1/dir2”)

This creates a relative symbolic link and shows how to read and resolve it. The link target “../file.txt” is relative to the link’s directory.

To use the link target, you often need to convert it to an absolute path using os.path.abspath or os.path.join with the link’s directory.

Reading Absolute Path Links

Symbolic links can also contain absolute paths. os.readlink returns the exact stored path, which may be absolute or relative.

absolute_link.py

import os

Create a file and absolute symlink

target = os.path.abspath(“target_file.txt”) link_name = “abs_link.txt”

with open(target, “w”) as f: f.write(“Absolute path test”)

os.symlink(target, link_name)

Read the absolute link

try: link_target = os.readlink(link_name) print(f"Link points to: {link_target}")

# Compare with resolved path
resolved = os.path.realpath(link_name)
print(f"Resolved path: {resolved}")

# Check if they match
if os.path.abspath(link_target) == resolved:
    print("Link target matches resolved path")
else:
    print("Warning: Link target differs from resolved path")

except OSError as e: print(f"Error: {e}")

Clean up

os.remove(link_name) os.remove(target)

This creates an absolute symbolic link and compares the raw link target with the fully resolved path using os.path.realpath.

For absolute links, the readlink result should match the resolved path unless intermediate links exist or filesystem changes occurred.

Error Handling

os.readlink raises OSError for various conditions. This example demonstrates comprehensive error handling for different failure scenarios.

error_handling.py

import os import errno

test_cases = [ “nonexistent_link”, # Doesn’t exist “regular_file.txt”, # Not a symlink “/proc/self/fd/0”, # Special file (may not be a link) "" # Empty path ]

Create a regular file for testing

with open(“regular_file.txt”, “w”) as f: f.write(“Test”)

for path in test_cases: print(f"\nTesting: {path}") try: target = os.readlink(path) print(f"Link target: {target}") except OSError as e: if e.errno == errno.EINVAL: print(“Not a symbolic link”) elif e.errno == errno.ENOENT: print(“Path does not exist”) elif e.errno == errno.ENOTDIR: print(“Component of path is not a directory”) else: print(f"Unexpected error: {e}")

Clean up

os.remove(“regular_file.txt”)

This tests various error conditions and handles them with specific error messages. Different errno values indicate different failure reasons.

Common errors include EINVAL (not a symlink), ENOENT (doesn’t exist), and EACCES (permission denied). Always handle these cases robustly.

Recursive Link Resolution

Symbolic links can point to other links. This example shows how to safely resolve nested links without infinite loops.

recursive_resolution.py

import os

def resolve_link(path, max_depth=10): “““Resolve a symbolic link recursively with cycle detection.””” original_path = path seen = set()

while max_depth > 0:
    try:
        if os.path.islink(path):
            if path in seen:
                raise OSError("Detected symbolic link loop")
            seen.add(path)
            path = os.path.join(os.path.dirname(path), os.readlink(path))
        else:
            return path
    except OSError as e:
        print(f"Error resolving {original_path}: {e}")
        return None
    max_depth -= 1

print(f"Maximum resolution depth reached for {original_path}")
return path

Create a chain of symbolic links

os.makedirs(“links”, exist_ok=True) with open(“links/target.txt”, “w”) as f: f.write(“Final target”)

os.symlink(“target.txt”, “links/link2.txt”) os.symlink(“link2.txt”, “links/link1.txt”)

Test resolution

print(“Resolved path:”, resolve_link(“links/link1.txt”))

Test cycle detection

os.symlink(“link1.txt”, “links/link2.txt”) # Create cycle print(“Resolved path:”, resolve_link(“links/link1.txt”))

Clean up

os.remove(“links/link1.txt”) os.remove(“links/link2.txt”) os.remove(“links/target.txt”) os.removedirs(“links”)

This implements safe recursive link resolution with cycle detection. The function follows links until finding a non-link or detecting a loop.

For production use, consider using os.path.realpath instead, which handles this automatically with proper system-level resolution.

Cross-Platform Considerations

Symbolic link behavior varies across platforms. This example demonstrates Windows-specific handling and fallback behavior.

cross_platform.py

import os import sys import platform

def read_link_safe(path): “““Cross-platform symbolic link reading with fallbacks.””” try: if platform.system() == “Windows”: # Windows requires special handling if sys.version_info >= (3, 8): # Python 3.8+ has proper symlink support return os.readlink(path) else: # Older Python on Windows may need admin privileges import ctypes kernel32 = ctypes.windll.kernel32 if not kernel32.CreateSymbolicLinkW: raise OSError(“Symbolic links not supported”) return os.readlink(path) else: # Unix-like systems return os.readlink(path) except (OSError, AttributeError) as e: print(f"Error reading link: {e}") return None

Test the function

test_link = “test_link” try: os.symlink(“target.txt”, test_link) print(“Link target:”, read_link_safe(test_link)) except OSError as e: print(f"Couldn’t create test link: {e}") finally: if os.path.exists(test_link): os.remove(test_link)

This shows platform-specific considerations for symbolic links. Windows has different requirements and capabilities than Unix-like systems.

On Windows, symbolic links often require administrator privileges or developer mode. The implementation also varies across Python versions.

Security Considerations

• Path validation: Always validate resolved paths before use

• Symlink attacks: Be aware of TOCTOU race conditions

• Privilege escalation: Malicious links can point to sensitive files

• Recursion limits: Implement cycle detection for recursive resolution

• Platform differences: Behavior varies between Unix and Windows

Best Practices

• Use os.path.realpath: For most cases, prefer this over manual resolution

• Handle errors: Always account for possible OSError conditions

• Validate paths: Check resolved paths against expected locations

• Limit recursion: Prevent infinite loops in custom resolution code

• Document assumptions: Note platform requirements and limitations

Source References

• Python os.readlink Documentation

• Linux readlink(2) man page

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Python tutorials.