Install phpredis MAC OSX

Install phpredis MAC OSX

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

Stefan Bogdanescu

Founder & Senior Architect

Installing PHP Redis on macOS: Resolving Homebrew and PECL Errors

If you are attempting to extend your PHP application with Redis capabilities on macOS, you likely encountered the standard suggestion: brew install php-redis. While this command works seamlessly on many Linux distributions or specific Homebrew setups, it often fails on macOS when using a standard PHP installation via Homebrew itself. The error message "invalid package name/package file 'php-redis'" or a generic Homebrew error indicates that the formula does not exist in your current tap list, or your PHP version is incompatible with the available formula.

The root cause usually lies in how Homebrew manages dependencies for different PHP versions. When you run brew install php-redis, Homebrew searches its default repository for a formula matching that exact name. However, Redis support is often built into the core PHP formula only when you specify the version explicitly or when it is not available as a standalone extension formula for your specific PHP build. If you are using PHP 7.4, 8.0, or 8.1 via Homebrew, you might find that php-redis is not a recognized formula in the default tap.

In these scenarios, the alternative command pecl install php-redis becomes the primary focus. This is the official method for installing PHP extensions after the core language is compiled. However, this path has its own set of hurdles on macOS. The error "invalid package name/package file 'php-redis'" typically appears because PECL looks for a .tgz or .tar.gz tarball hosted on the PECL website to download and compile. If the release for your specific PHP version (e.g., php-8.1-redis) is not yet available on the PECL archives, or if the package has been renamed, the installation will fail immediately. You cannot simply run pecl install php-redis without specifying the correct version prefix like php81 or php74.

To resolve this, you must first identify your exact PHP version using php -v. Once confirmed, navigate to the directory where PECL looks for extensions and attempt a version-specific installation. For example, if you are running PHP 8.0, the command would be:

pecl install redis

Note that modern versions of PECL often do not require the php- prefix in the command itself; simply running pecl install redis will target the correct extension for your active PHP build. If this command fails with a network timeout or missing dependencies, ensure you have installed the necessary build tools:

brew install autoconf automake libtool pkg-config gcc

After a successful installation, do not forget to reload your configuration. You can enable the extension by adding extension=redis to your php.ini file, either via php --ini or by editing the file directly in /etc/php.ini.

There is also the option of compiling PHP from source with Redis support pre-enabled. This approach offers more control over the build process but requires setting up a complex environment including libevent and igbinary dependencies beforehand. Unless you have specific requirements for static linking or custom memory management, sticking to the dynamic PECL installation is generally safer and easier to maintain on macOS.

If you are working within a Laravel project specifically, having Redis configured correctly is essential for caching queues and sessions. While some managed hosting environments handle this automatically, local development on macOS requires manual intervention. For robust production setups or if you need enterprise-grade support for your PHP infrastructure, resources like https://laravelcompany.com provide detailed guides on configuring the LEMP stack and ensuring Redis is properly integrated into your workflow. However, for standalone macOS installations, mastering pecl commands and understanding the versioning nuances of Homebrew formulas is the key to a stable setup.

Our network