Composer Install: Fixing PHP Memory Limit Exhausted Error on macOS

Resolve 'memory limit exhausted' errors during Composer install/update on macOS by adjusting PHP's CLI memory_limit, cleaning cache, or using Docker strategies.

Resolve 'memory limit exhausted' errors during Composer install/update on macOS by adjusting PHP's CLI memory_limit, cleaning cache, or using Docker strategies.

When working on PHP projects on your local macOS development environment, particularly with frameworks like Laravel, Symfony, or Magento, you might encounter a frustrating "memory limit exhausted" error during Composer operations. This typically occurs when Composer attempts to resolve dependencies or install packages, requiring more memory than PHP's CLI configuration allows. This guide will walk you through diagnosing and resolving this common issue.

Symptom & Error Signature

You will typically observe a fatal PHP error output directly in your terminal when executing composer install, composer update, or even composer require. The Composer process will halt abruptly, presenting an error message similar to the following:

$ composer install
Loading composer repositories with package information
Installing dependencies from lock file (including require-dev)
Verifying lock file contents with composer.json requirements
No installation report was found with the current Composer version.
Package operations: 198 installs, 0 updates, 0 removals
  - Installing vendor/package-name (1.0.0): Extracting archive
PHP Fatal error:  Allowed memory size of 1073741824 bytes exhausted (tried to allocate 2097152 bytes) in /Users/youruser/project-name/vendor/composer/2de642f5/Symfony-Polyfill-Php80-v1.28.0-0-gc5b6823/Php80.php on line 58

The specific file and line number might vary, but the core message Allowed memory size of X bytes exhausted is the definitive indicator of this problem.

Root Cause Analysis

This error signifies that the PHP interpreter, when invoked by Composer, has hit its configured memory_limit. Several factors contribute to this on a local macOS environment:

  1. Insufficient memory_limit: The most common cause is that the memory_limit directive in the PHP CLI's php.ini file is set too low (e.g., 128M, 256M, or 512M) for the current Composer operation. Modern PHP applications, especially those with many dependencies, often require 1GB or more for Composer to complete successfully.
  2. Large Dependency Graph: Complex projects, particularly those built on popular frameworks, involve a vast number of packages and their recursive dependencies. Resolving this graph consumes significant memory.
  3. Outdated Composer/PHP: Older versions of Composer or PHP might have less optimized memory management, exacerbating the issue. Composer 2.x is significantly more memory-efficient than 1.x.
  4. Corrupted Composer Cache: A stale or corrupted Composer cache can sometimes lead to excessive memory consumption during dependency resolution.
  5. Multiple PHP Installations: On macOS, it's common to have multiple PHP versions installed (e.g., system PHP, Homebrew PHP, MAMP/XAMPP PHP, Dockerized PHP). Composer might be using a php.ini from an unexpected PHP installation with a lower memory limit.

Step-by-Step Resolution

Follow these steps to diagnose and resolve the Composer memory limit issue on your macOS local environment.

1. Identify the Active PHP CLI php.ini

Before making any changes, it's crucial to identify which php.ini file your Composer CLI is actually using.

# Check the PHP version Composer is using
which php
php -v

# Find the php.ini file loaded by the CLI
php --ini

# Or, use Composer's built-in diagnosis tool
composer diagnose

The output of php --ini will show Loaded Configuration File and potentially Scan for additional .ini files in. This is the file you need to edit. For Homebrew PHP (the most common installation method on macOS), the php.ini path typically looks like:

  • ARM-based Macs (M1/M2/M3): /opt/homebrew/etc/php/<php-version>/php.ini (e.g., /opt/homebrew/etc/php/8.2/php.ini)
  • Intel-based Macs: /usr/local/etc/php/<php-version>/php.ini (e.g., /usr/local/etc/php/8.2/php.ini)

2. Increase PHP CLI memory_limit

Edit the identified php.ini file to increase the memory_limit.

# Example for Homebrew PHP 8.2 on ARM Mac
sudo nano /opt/homebrew/etc/php/8.2/php.ini

Locate the memory_limit directive. If it's commented out (prefixed with ;), uncomment it. Change its value to a more generous amount, such as 1G (1 Gigabyte) or 2G.

; Maximum amount of memory a script may consume (128MB)
; http://php.net/memory-limit
memory_limit = 2G

While setting memory_limit = -1 (unlimited memory) is a common quick fix for Composer, it's generally not recommended for production environments or if you are unsure about runaway scripts. For a local development environment and Composer operations, it's generally safe. However, a specific high value like 2G is usually sufficient and safer.

Save the file and exit the editor. You don't need to restart any services for CLI changes to take effect.

3. Temporarily Override Memory Limit (CLI)

If you prefer not to modify your global php.ini or need a quick one-off solution, you can override the memory_limit directly when running the Composer command.

php -d memory_limit=2G /usr/local/bin/composer install
# Or for unlimited:
php -d memory_limit=-1 /usr/local/bin/composer install

Ensure /usr/local/bin/composer is the correct path to your Composer executable. You can find this by running which composer. If php is not directly linked to your desired PHP version, you might need to specify the full path, e.g., /opt/homebrew/opt/[email protected]/bin/php -d memory_limit=2G $(which composer) install.

4. Clear Composer Cache

A corrupted or excessively large Composer cache can sometimes contribute to memory issues. Clearing it can help.

composer clear-cache

5. Update Composer to the Latest Version

Composer 2.x introduced significant performance and memory usage improvements compared to 1.x. Ensure you are running the latest version.

composer self-update
composer self-update --2 # Force update to Composer 2.x

6. Adjust Composer Process Timeout (If Applicable)

In some rare cases, if Composer takes an extremely long time to resolve dependencies, it might hit a process timeout before memory exhaustion. While not directly a memory issue, it can sometimes manifest similarly if the underlying problem is a large dependency graph.

# Set a global process timeout to 600 seconds (10 minutes)
composer config -g process-timeout 600

7. Docker Container Resolution (If Using Docker)

If you're running your PHP environment via Docker (e.g., with docker-compose), the php.ini file will be inside your container, not on your macOS host system.

  1. Access the container:

    docker-compose exec php-fpm bash # Or your service name, e.g., web, app

  2. Locate php.ini inside the container:

    php --ini

    Common paths inside Docker containers: /etc/php/<php-version>/cli/php.ini or /usr/local/etc/php/php.ini.

  3. Edit php.ini within the container: Use nano or vi to modify memory_limit as described in Step 2.

    nano /etc/php/8.2/cli/php.ini

  4. Restart the PHP service in the container (if necessary for PHP-FPM): For CLI changes, a restart is often not strictly required, but for safety, if you modified the FPM php.ini, restart the service or the container.

    exit # Exit the container's shell
docker-compose restart php-fpm # Restart your PHP service

  5. Persistent Docker Configuration (Recommended): For a more robust and persistent solution, modify your Dockerfile or docker-compose.yml to set the memory_limit.

    Using Dockerfile (build time):

    FROM php:8.2-fpm-alpine

# Copy a custom php.ini file
COPY php.ini /usr/local/etc/php/php.ini

# OR, set directly via sed (less readable, but useful for small changes)
RUN sed -i 's/memory_limit = .*/memory_limit = 2G/' /usr/local/etc/php/php.ini

# ... rest of your Dockerfile

    Then, ensure your php.ini file in the same directory as your Dockerfile contains memory_limit = 2G.

    Using docker-compose.yml (runtime): You can override php.ini directives using the PHP_INI_SCAN_DIR environment variable or by mounting a custom php.ini file.

    version: '3.8'
services:
  php:
    build: .
    volumes:
      - ./src:/var/www/html
      # Mount a custom php.ini specifically for this service
      - ./docker/php/php.ini:/usr/local/etc/php/php.ini # Adjust path
    environment:
      # Alternatively, use extra_hosts or other network settings
      # For a quick override without mounting a file:
      # PHP_INI_SCAN_DIR: "/usr/local/etc/php-fpm.d:/usr/local/etc/php"
      # Then add a .ini file like 99-custom.ini to one of these dirs with:
      # memory_limit=2G
    # ... other configurations

    After modifying docker-compose.yml or Dockerfile, rebuild and restart your services:

    docker-compose up --build -d

After applying these steps, try running your composer install or composer update command again. The memory limit error should now be resolved.