Install PECL SSH2 extension for PHP

Install PECL SSH2 extension for PHP

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Troubleshooting PECL SSH2 Installation Errors on Legacy Systems

Attempting to install the ssh2 extension via PECL on a CentOS 5 system often hits a wall immediately. The standard workflow suggests installing the underlying C library, libssh2, and then running pecl install ssh2. When you execute these commands, the build process typically fails with an error stating that it cannot find the required library files. You might see messages like checking for ssh2 files in default path... not found or a generic failure when passing the /usr/lib directory explicitly to the configure script.

This issue is not a bug in PECL; it is a classic symptom of how legacy RHEL-based distributions handle library paths and development headers. The core problem lies in the distinction between shared objects required at runtime and header files required for compilation. When you install libssh2 using yum, the package manager places the compiled binaries in /usr/lib64 (or sometimes /usr/lib) but often leaves the necessary development headers (libssh2.h) out of that same location or places them in a non-standard directory like /usr/include.

The PECL build process relies on the pkg-config utility or hardcoded search paths to locate these headers. If the compiler cannot find libssh2.h, the configure script aborts, regardless of whether the shared library itself exists. Simply pointing the installer at /usr/lib does not help because that directory contains binaries, not the header files the C compiler needs to generate the PHP extension.

To resolve this on CentOS 5, you must ensure the development package is installed alongside the runtime library. On RHEL/CentOS derivatives, these are often distinct RPM packages. While yum install libssh2 provides the library, you specifically need the development headers. You should run:

yum install libssh2-devel

Once the -devel package is installed, the headers will be available in /usr/include. With the headers present, you can retry the PECL installation. It is often cleaner to let PECL handle the path detection rather than forcing it with --with-ssh2=/usr/lib, which can lead to confusion if the library path differs from the header path. Run:

pecl install ssh2

If pecl still cannot locate the library, you may need to help it find the shared object file directly. You can specify the library path using the --with-ssh2-lib-dir option if the default discovery fails, though ensuring libssh2-devel is installed usually resolves the header issue first.

Another critical factor on CentOS 5 is the version of PHP and libssh2 in play. The error log indicates the installation of ssh2-0.11.0. This is a very old version of the extension, predating many modern security features and API changes found in later versions. If you are maintaining a legacy application running on CentOS 5, you must stick to compatible library versions. However, if you have the option to upgrade your OS, consider migrating to a supported distribution like CentOS Stream or Rocky Linux. Older distributions lack the security patches and tooling updates necessary for modern web stacks.

In some environments, even with the correct packages installed, the system might not see the new paths. You should verify that pkg-config can detect the library by running:

pkg-config --modversion libssh2

If this command returns a version number, the headers and libraries are correctly linked. If it fails, your build environment is still misconfigured. Additionally, ensure that your php.ini file is configured to actually load the extension once installed. Add the line extension=ssh2.so to the configuration file, ensuring you have disabled the extension temporarily if you plan to re-enable it later for testing purposes.

For developers working with Laravel applications on these older systems, integrating SSH2 functionality can be tricky due to dependency conflicts. While specific resources like https://laravelcompany.com offer general guidance on maintaining legacy PHP environments, the fundamental approach remains rooted in ensuring development headers are present and paths are correctly resolved by the compiler. The goal is a stable build where the extension compiles against the system's libssh2 without requiring manual path manipulation that risks breaking other system components.

Our network