$ php8.1 -v
PHP Fatal error: Unable to start pcre module in Unknown on line 0
Cause
The cause of the error is that PHP has a hard dependency on pcre. PHP ships with pcre bundled in and normally things work out of the box without
you having to do anything. But in my case – since I like doing things the hard way – I had installed pcre manually from source code earlier when I
installed SWIG. The binary that gets built by following this procedure
gets installed under /usr/local/lib but PHP does not like it and it gives above error
PHP Fatal error: Unable to start pcre module in Unknown on line 0 if you try to use your own pcre instead of the pcre that comes with PHP.
This is what ABI – application binary interface – (in)compatibility refers to.
| API incompatibility | ABI incompatibility | |
|---|---|---|
| Caught at | Compile time | Runtime |
| Visible in | Source code | Compiled binaries |
| Example | Function doesn’t exist | Function exists but calling convention differs |
Fix
The fix is to change the order of precedence so that PHP’s pcre which gets installed under /lib/x86_64-linux-gnu/libpcre2-8.so.0 takes precedence over the homegrown /usr/local/lib/libpcre2-8.so.0. We can do that by adding a config directive in /etc/ld.so.conf.d. Do that by running:
echo "/lib/x86_64-linux-gnu" | sudo tee /etc/ld.so.conf.d/force-system-pcre2.conf
After this I got:
$ ldconfig -p | grep libpcre
libpcre2-8.so.0 (libc6,x86-64) => /lib/x86_64-linux-gnu/libpcre2-8.so.0
libpcre2-8.so.0 (libc6,x86-64) => /usr/local/lib/libpcre2-8.so.0
libpcre2-posix.so.3 (libc6,x86-64) => /usr/local/lib/libpcre2-posix.so.3
libpcreposix.so.3 (libc6,x86-64) => /lib/x86_64-linux-gnu/libpcreposix.so.3
libpcre.so.3 (libc6,x86-64) => /lib/x86_64-linux-gnu/libpcre.so.3
and I am able to run PHP:
$ php8.1 -v
PHP 8.1.2-1ubuntu2.23 (cli) (built: Jan 7 2026 08:37:41) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
with Zend OPcache v8.1.2-1ubuntu2.23, Copyright (c), by Zend Technologies