Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PHP cannot load the phpredis extension (redis.so)

ErrorPHP Warning: PHP Startup: Unable to load dynamic library 'redis.so'

Short answer

PHP loaded a php.ini that names redis.so, but no file with that name exists for this PHP build, or the CLI and FPM read different ini files. Find which php.ini PHP reads, install the extension for the same PHP version with PECL or your package manager, then check with php --ri redis.

  • Applies to PHP 8.3, PHP 8.4, phpredis 6, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Show which ini files PHP reads and whether the extension is loaded.

    php --ini
    php -m | grep -i redis
    php -i | grep -E "^extension_dir"
  2. 2Match what you see, then jump to its fix

    1. 1php -m prints nothing for redis, and the extension folder has no redis.so.The extension was never installed for this PHPFix
    2. 2The file exists but PHP warns it cannot load it, or you have several PHP versions installed.The extension was built for a different PHP versionFix
    3. 3php -m works in the terminal, but the website (PHP-FPM or Apache) still says Class 'Redis' not found.The ini line is in the wrong file, or the web server reads another oneFix

What does the error look like?

  • PHP Warning: PHP Startup: Unable to load dynamic library 'redis.so'

Cause 1 of 3

The extension was never installed for this PHP

1Check

A line extension=redis.so in php.ini does nothing without the compiled file in extension_dir.

ls "$(php -r 'echo ini_get("extension_dir");')" | grep redis

2Fix

Install it. PECL builds it for the PHP that owns the pecl command; Linux distributions also ship packages.

pecl install redis
# or on Fedora/RHEL family
sudo dnf install php-redis

3Verify

PHP reports the extension and its version.

php --ri redis

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

The extension was built for a different PHP version

1Check

pecl and phpize belong to one PHP. If php --version and pecl config-show disagree, the module was built for another API version.

php --version
pecl config-show | grep -E "php_ini|ext_dir"

2Fix

Run phpize and the build from the PHP you actually use, then copy the module, or install the package matching that version.

phpize
./configure
make && make install

3Verify

Restart PHP and list modules.

php -m | grep -i redis

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

The ini line is in the wrong file, or the web server reads another one

1Check

The command line and FPM often load different php.ini files and conf.d folders.

php --ini
php-fpm8.3 -i | grep "Loaded Configuration File"

2Fix

Enable the extension in the ini that FPM loads (a redis.ini in its conf.d folder is enough), then restart FPM.

# Debian/Ubuntu package layout; use the conf.d folder that php --ini lists on other systems
echo "extension=redis.so" | sudo tee /etc/php/8.3/fpm/conf.d/20-redis.ini
sudo systemctl restart php8.3-fpm

3Verify

A phpinfo page or php-fpm -m lists redis.

php-fpm8.3 -m | grep -i redis

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Pin the PHP version in your server setup and install the extension from the same source as PHP.
  • Check php --ri redis in deployment, not only in the shell you tested in.
  • Restart PHP-FPM or Apache after every extension change.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

CodeIgniter 4 cannot write its cache files

CodeIgniter\Cache\Exceptions\CacheException: Cache unable to write to /var/www/app/writable/cache/

CodeIgniter 4's file cache needs a cache directory that the web server can really write to.

2 causes, each with a fix

Back end

CodeIgniter 3 loads the model but the property is undefined

The model name you are loading is the name of a resource that is already being used: user

CodeIgniter 3 expects a model file named like its class, with the first letter capitalised, for example User_model.php holding class User_model.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.