How to Fix OpenSSL Error: 'libssl.so.3: Cannot Open Shared Object File' (No Such File or Directory)

Table of Contents#

1. What Causes the Error?
2. Prerequisites
3. Step-by-Step Solutions by Operating System
   • Ubuntu/Debian-Based Systems
   • Fedora/RHEL/CentOS Systems
   • Arch Linux/Manjaro
   • macOS
   • Windows Subsystem for Linux (WSL)
4. Troubleshooting Common Issues
5. Preventive Measures
6. Conclusion
7. References

What Causes the Error?#

The libssl.so.3 error occurs when the system cannot find the OpenSSL 3.x shared library. Here are the most common causes:

• Missing OpenSSL 3.x Installation: The library libssl.so.3 is part of OpenSSL 3.0 or later. If your system only has older versions (e.g., OpenSSL 1.1.1), this file won’t exist.
• Incorrect Library Path: The library may be installed but not in the system’s default library search path (e.g., /usr/lib, /usr/local/lib).
• Architecture Mismatch: The installed libssl.so.3 is for a different architecture (e.g., 32-bit vs. 64-bit) than the application trying to load it.
• Corrupted Installation: OpenSSL 3.x may be installed, but the library file is missing or corrupted due to incomplete updates or disk errors.

Prerequisites#

Before starting, ensure you have:

• sudo/root access: To install packages or modify system files.
• Basic command-line familiarity: You’ll need to run terminal commands.
• OS version info: Know your Linux distribution (e.g., Ubuntu 22.04, Fedora 38) or macOS version. Check with:

  # Linux: Check OS version  
  lsb_release -a  # Ubuntu/Debian  
  cat /etc/os-release  # All Linux  
  # macOS: Check version  
  sw_vers  

Step-by-Step Solutions by Operating System#

1. Ubuntu/Debian-Based Systems (Ubuntu 22.04+, Debian 12+)#

Ubuntu 22.04 and Debian 12 include OpenSSL 3.x in their default repositories. For older versions (e.g., Ubuntu 20.04), see the Troubleshooting section.

Step 1: Check if OpenSSL 3.x is Installed#

First, verify if OpenSSL 3.x is already installed:

openssl version  

If the output shows OpenSSL 3.0.x or higher, skip to Step 3. If it shows 1.1.1 or lower, proceed.

Step 2: Install OpenSSL 3.x#

Install the libssl3 package (which includes libssl.so.3):

sudo apt update && sudo apt install libssl3  

Step 3: Verify the Library Exists#

Check if libssl.so.3 is now present:

find /usr/lib -name "libssl.so.3"  

You should see a path like /usr/lib/x86_64-linux-gnu/libssl.so.3.

Step 4: Refresh the Library Cache#

Update the system’s library cache to ensure the new library is recognized:

sudo ldconfig  

Step 5: Test the Application#

Rerun the application that triggered the error. It should now load libssl.so.3 successfully.

2. Fedora/RHEL/CentOS Systems (Fedora 36+, RHEL 9+, CentOS Stream 9+)#

Fedora 36+ and RHEL 9+ ship with OpenSSL 3.x. For older RHEL/CentOS versions, use EPEL or compile from source (see Troubleshooting).

Step 1: Check OpenSSL Version#

openssl version  

Step 2: Install OpenSSL 3.x Libraries#

On Fedora:

sudo dnf install openssl-libs  

On RHEL/CentOS Stream:

sudo dnf install openssl-libs  # RHEL 9+ includes OpenSSL 3.x by default  

Step 3: Verify and Refresh the Cache#

# Check for libssl.so.3  
find /usr/lib64 -name "libssl.so.3"  
# Refresh cache  
sudo ldconfig  

3. Arch Linux/Manjaro#

Arch Linux and Manjaro use the latest OpenSSL by default. If the library is missing, update your system:

Step 1: Update System Packages#

sudo pacman -Syu openssl  

Step 2: Verify Installation#

find /usr/lib -name "libssl.so.3"  
# Should return /usr/lib/libssl.so.3  
sudo ldconfig  

4. macOS#

macOS users can install OpenSSL 3.x via Homebrew:

Step 1: Install Homebrew (if not installed)#

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"  

Step 2: Install OpenSSL 3.x#

brew install openssl@3  

Step 3: Link the Library (if needed)#

Homebrew installs OpenSSL in /usr/local/opt/openssl@3/lib. If your application can’t find it, add this path to the library search path:

# Temporary fix (for the current terminal session)  
export LD_LIBRARY_PATH="/usr/local/opt/openssl@3/lib:$LD_LIBRARY_PATH"  
# Permanent fix (add to ~/.bashrc or ~/.zshrc)  
echo 'export LD_LIBRARY_PATH="/usr/local/opt/openssl@3/lib:$LD_LIBRARY_PATH"' >> ~/.bashrc  
source ~/.bashrc  

5. Windows Subsystem for Linux (WSL)#

WSL uses the same package managers as its underlying Linux distribution (e.g., Ubuntu WSL uses apt). Follow the steps for your WSL distro (e.g., Ubuntu/Debian).

Troubleshooting Common Issues#

Issue 1: "Package libssl3 not found" (Older Linux Distributions)#

If your OS (e.g., Ubuntu 20.04, Debian 11) doesn’t have libssl3 in its default repos, use backports or compile OpenSSL 3.x from source:

Option 1: Use Backports (Ubuntu/Debian)#

For Ubuntu 20.04:

sudo add-apt-repository ppa:ubuntu-toolchain-r/test  
sudo apt update  
sudo apt install libssl3  

Option 2: Compile OpenSSL 3.x from Source (Advanced)#

1. Download the latest OpenSSL 3.x source from openssl.org:

   wget https://www.openssl.org/source/openssl-3.1.4.tar.gz  
   tar -xf openssl-3.1.4.tar.gz  
   cd openssl-3.1.4  

2. Configure and install:

   ./config --prefix=/usr/local/openssl --openssldir=/usr/local/openssl  
   make  
   sudo make install  

3. Link the library to a system path:

   sudo ln -s /usr/local/openssl/lib64/libssl.so.3 /usr/lib/libssl.so.3  
   sudo ldconfig  

Issue 2: Library Exists but Error Persists#

If libssl.so.3 is installed but the error continues:

• Check architecture: Ensure the library matches the application’s architecture (32-bit vs. 64-bit). For 32-bit apps on 64-bit systems, install the 32-bit library (e.g., libssl3:i386 on Ubuntu).

  # Check library architecture  
  file /usr/lib/x86_64-linux-gnu/libssl.so.3  
  # Output should show "ELF 64-bit LSB shared object" for 64-bit.  

• Update LD_LIBRARY_PATH: Temporarily add the library path to the environment variable:

  export LD_LIBRARY_PATH=/path/to/libssl.so.3/directory:$LD_LIBRARY_PATH  

Issue 3: Corrupted Library File#

If the library is corrupted, reinstall OpenSSL:

# Ubuntu/Debian  
sudo apt reinstall libssl3  
# Fedora  
sudo dnf reinstall openssl-libs  

Preventive Measures#

To avoid future libssl.so.3 errors:

• Keep your system updated: Regularly run sudo apt update && sudo apt upgrade (Ubuntu/Debian) or sudo dnf update (Fedora/RHEL) to get the latest libraries.
• Use official packages: Avoid manual installations unless necessary—package managers (apt, dnf, pacman) handle dependencies like libssl.so.3 automatically.
• Check dependencies before installing apps: Use ldd <application> to list an app’s required libraries and verify they exist.

Conclusion#

The libssl.so.3 error is typically caused by a missing OpenSSL 3.x library. By installing the correct package for your OS, refreshing the library cache, and verifying the installation, you can resolve the issue quickly. For older systems or edge cases, use backports or compile from source (with caution).

With these steps, your applications should now load libssl.so.3 and run securely.

References#

• OpenSSL Official Documentation
• Ubuntu libssl3 Package
• Fedora openssl-libs Package
• Arch Linux OpenSSL Package
• ldconfig Man Page: man ldconfig
• ldd Man Page: man ldd