Configuring Library Paths in Linux: LD_LIBRARY_PATH and ldconfig

Introduction / Why This Is Needed

Dynamic libraries (.so files in Linux) are a key mechanism for saving memory and simplifying program updates. However, the system must know where to look for these libraries. By default, standard directories (/lib, /usr/lib, etc.) are checked, but if you install software in a non-standard location (e.g., /opt/app/lib), you need to explicitly specify that path.

This guide explains how to add custom directories to the library search path using three main methods. After completing it, you will be able to:

• Run programs that use non-system libraries.
• Deploy your own software builds without conflicts.
• Diagnose error while loading shared libraries errors.

Prerequisites / Preparation

Before you begin, ensure that:

1. You have terminal access (SSH or local console).
2. For system-wide changes (Method 3), superuser privileges (sudo) are required.
3. You know the absolute path to the directory containing the libraries (e.g., /home/user/myproject/lib). Relative paths will not work.
4. This directory contains files with the .so extension (or symlinks to them).

Step-by-Step Instructions

Step 1: Check Current Settings

Before making any changes, see which paths are already configured.

# 1. Check the LD_LIBRARY_PATH variable (if empty, output will be blank)
echo "Current LD_LIBRARY_PATH: $LD_LIBRARY_PATH"

# 2. View system paths from ld.so configuration
# -v: verbose output, 2>/dev/null: suppress warnings about 32-bit libraries
ldconfig -v 2>/dev/null | grep -v '^\s' | head -20

What you will see:
The first command shows user-specific paths (if any were set). The second shows all directories the system knows about after the last ldconfig run. These are standard paths (/lib, /usr/lib) and paths from files in /etc/ld.so.conf.d/.

Step 2: Temporary Path Addition (For Current Session)

This method is suitable for quick testing or running a program once. The path only lasts for the current terminal window.

# Replace /path/to/libraries with your actual path
export LD_LIBRARY_PATH="/path/to/libraries:$LD_LIBRARY_PATH"

# Verify the variable was set
echo $LD_LIBRARY_PATH

Important:

• :$LD_LIBRARY_PATH at the end adds the new path to the beginning of the list, giving it priority.
• The setting will be reset after you close the terminal.

Step 3: Permanent Path Addition for Current User

To make changes persist between restarts, add the export to your shell's configuration file.

# 1. Open ~/.bashrc (for bash) or ~/.zshrc (for zsh) in an editor
nano ~/.bashrc

# 2. Add this line to the end of the file (replace the path):
export LD_LIBRARY_PATH="/opt/mylibs:$LD_LIBRARY_PATH"

# 3. Save (Ctrl+O, Enter) and close (Ctrl+X)

# 4. Apply changes to the current session
source ~/.bashrc

# 5. Verify
echo $LD_LIBRARY_PATH

Note:
This method affects only your user and only when starting interactive shells. For GUI applications, you may need to add it to ~/.profile or ~/.xprofile.

Step 4: Add a System-Wide Path (For All Users)

This is the recommended approach for libraries that should be available to all programs and users. It is more stable and does not depend on environment variables.

# 1. Create a new configuration file in /etc/ld.so.conf.d/
sudo nano /etc/ld.so.conf.d/custom.conf

# 2. Enter the absolute path to your library directory (one path per line):
/usr/local/lib/mylibs

# 3. Save and close the editor.

# 4. Update the ld.so cache (this is required!)
sudo ldconfig

# 5. Verify the path was added:
ldconfig -v 2>/dev/null | grep mylibs

Why this is better:

• Does not require setting environment variables for each user.
• Works for all programs, including systemd services and GUI applications.
• It is the standard used by distributions (.deb and .rpm packages add their files to /etc/ld.so.conf.d/).

Step 5: Verify the Configuration

After using any of the methods above, check that the system recognizes your libraries.

# Method 1: Use ldd on a specific executable
# Replace /usr/bin/your_program with the actual path
ldd /usr/bin/your_program | grep "not found"

# If output is empty — all libraries were found.
# If there are lines with "not found", the path is not configured correctly.

# Method 2: Run the program that was previously failing.
# It should now work.

# Method 3: Check the ldconfig cache
ldconfig -p | grep library_name
# Example: ldconfig -p | grep libcustom.so

Potential Issues

Issue: "Permission denied" when using sudo ldconfig

Cause: You are trying to write to /etc/ld.so.conf.d/ without superuser privileges.
Solution: All operations on system files (/etc/ld.so.conf.d/, /etc/ld.so.conf) require sudo.

Issue: Library is still not found after configuration

Cause 1: You used a relative path (e.g., ./lib).
Solution: Always use an absolute path (/home/user/project/lib).

Cause 2: The library file has incorrect permissions.
Solution: Ensure the .so file is readable by everyone:

ls -l /path/to/library/libexample.so
# Should be: -rwxr-xr-x or at least -rw-r--r--
sudo chmod 755 /path/to/library/libexample.so

Cause 3: You added the path to LD_LIBRARY_PATH, but the variable was not exported.
Solution: Check export | grep LD_LIBRARY_PATH. If the output is empty, add export to your configuration file.

Cause 4: The path was added to /etc/ld.so.conf.d/, but ldconfig was not run.
Solution: Always run sudo ldconfig after editing files in /etc/ld.so.conf.d/.

Issue: Library conflict (program breaks after adding path)

Cause: Your directory contains a library with the same name as a system library, but a different version.
Solution:

1. Check which library is being loaded: ldd /path/to/program | grep conflicting_library.
2. If yours is loaded instead of the system one — that's the problem. Rename your library or use isolation via patchelf or chrpath to modify the executable's RPATH.
3. Temporary workaround: remove the path from LD_LIBRARY_PATH or move the library to a different directory.

Issue: Settings not applied for GUI applications

Cause: Graphical shells (GNOME, KDE) do not always read ~/.bashrc.
Solution: For permanent paths, use Method 4 (system-wide via ld.so.conf.d). If you need it only for your user, add export LD_LIBRARY_PATH=... to ~/.profile or ~/.xprofile.

# Example for ~/.profile
if [ -z "$LD_LIBRARY_PATH" ]; then
    export LD_LIBRARY_PATH="/home/user/myapp/lib"
else
    export LD_LIBRARY_PATH="/home/user/myapp/lib:$LD_LIBRARY_PATH"
fi