PHP cannot load the phpredis extension (redis.so)
PHP 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 1
php -m prints nothing for redis, and the extension folder has no redis.so.The extension was never installed for this PHPFix - 2
The 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
php -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
- 1
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 redis2Fix
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-redis3Verify
PHP reports the extension and its version.
php --ri redisConfirmed by raw.githubusercontent.com
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 install3Verify
Restart PHP and list modules.
php -m | grep -i redisConfirmed by raw.githubusercontent.com
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-fpm3Verify
A phpinfo page or php-fpm -m lists redis.
php-fpm8.3 -m | grep -i redisConfirmed by raw.githubusercontent.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Spotless LaundryAn on-demand laundry app: Flutter on a Laravel back end, with Firebase for live updates.
- EZ EstimaterConstruction quoting and job tracking for contractors, on a Laravel and Firebase stack.
Related fixes
Back end
Laravel says Class "Redis" not found when using phpredis
Class 'Redis' not found
Laravel uses the phpredis PHP extension by default, so a missing or disabled extension gives Class "Redis" not found.
3 causes, each with a fixBack end
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fixBack end
AWS SDK for PHP cannot get credentials from the instance profile metadata server
Error retrieving credentials from the instance profile metadata server.
The SDK tries the EC2 instance metadata service when it has no valid credentials from anywhere earlier in its chain.
4 causes, each with a fixBack end
AWS SDK for PHP rejects requests: the signature is from the future
Signature not yet current: {date} is still later than {date}
AWS compares the timestamp in your signed request with its own clock.
2 causes, each with a fixBack 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 fixBack 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