Fixing Composer ‘Memory Limit Exhausted’ Error on Ubuntu 22.04 LTS

Resolve Composer 'memory limit exhausted' errors on Ubuntu 22.04 LTS during PHP package installations. Optimize PHP CLI and web server memory for smoother development and deployments.

Introduction

Encountering a "Memory Limit Exhausted" error during a Composer operation, such as composer install or composer update, is a common frustration for PHP developers and system administrators. This issue typically manifests on Ubuntu 22.04 LTS when Composer, acting as PHP's dependency manager, attempts to allocate more memory than the PHP CLI process is allowed by its configuration. This guide will walk you through diagnosing and resolving this memory allocation bottleneck, ensuring your PHP package installations proceed without interruption.

Symptom & Error Signature

When the PHP CLI process, driven by Composer, hits its configured memory ceiling, you will typically see an error message similar to the following in your terminal output:

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 20480 bytes) in phar:///usr/local/bin/composer/src/Composer/DependencyResolver/Solver.php on line 294

Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 20480 bytes) in phar:///usr/local/bin/composer/src/Composer/DependencyResolver/Solver.php on line 294

The exact file path and line number might vary slightly depending on your Composer version and the specific operation, but the core message "Allowed memory size of X bytes exhausted" remains consistent. You might also see a hint from Composer itself:

Check https://getcomposer.org/doc/articles/troubleshooting.md#memory-limit-issues for more info on how to handle out of memory errors.

Root Cause Analysis

The "Memory Limit Exhausted" error during Composer operations is almost always due to the PHP CLI's memory_limit setting being too low for the task at hand. Here's a deeper dive into the underlying reasons:

1. Insufficient memory_limit for PHP CLI:

   • By default, PHP CLI often has a memory_limit set to 128M, 256M, or 512M. While sufficient for simple scripts, complex PHP projects (e.g., large Laravel, Symfony, or Magento applications) with numerous dependencies, especially dev dependencies, can quickly exceed this limit during dependency resolution.
   • Composer's dependency solver (e.g., DependencyResolver/Solver.php) is memory-intensive, particularly with a large dependency graph or when dealing with conflicting package versions.

2. Growing Project Complexity:

   • As a project evolves and acquires more packages or deeper dependency trees, the memory required by Composer to analyze and install these packages increases. Older projects, or those with many legacy dependencies, can be particularly demanding.

3. Development vs. Production Environments:

   • Development environments often install require-dev dependencies, which significantly increase the total number of packages and, consequently, the memory footprint of Composer operations. Production deployments often use --no-dev, reducing memory needs.

4. Outdated Composer or PHP:

   • While less common, older versions of Composer or PHP might have less optimized memory management. Keeping both up-to-date generally improves performance and reduces memory consumption.

5. System-Wide RAM Limitations (less common as direct cause for this error):

   • While the error message points to PHP's configured limit, it's worth noting that if the entire server has very low RAM (e.g., a small VPS), even a high memory_limit setting might eventually lead to system-level Out-Of-Memory (OOM) killer events, but the initial error will still be PHP-specific.

Step-by-Step Resolution

Here's how to systematically resolve the Composer memory limit issue on your Ubuntu 22.04 LTS server.

1. Temporary Fix: Overriding Memory Limit for a Single Composer Run

For immediate relief or quick testing, you can override the PHP CLI memory_limit directly when invoking Composer.

• Using php -d: This method directly instructs the PHP interpreter to use a specific memory_limit.

  php -d memory_limit=-1 /usr/local/bin/composer install
  

  Or, if composer is symlinked in your PATH:

  php -d memory_limit=-1 $(which composer) install
  

  The -1 value tells PHP to use an unlimited memory limit. While effective, it should be used cautiously on systems with limited RAM, as it could potentially lead to system instability if a process truly consumes all available memory.

• Using COMPOSER_MEMORY_LIMIT environment variable: Composer itself respects an environment variable to set its memory limit.

  COMPOSER_MEMORY_LIMIT=2G composer install
  

  You can also use -1 for unlimited:

  COMPOSER_MEMORY_LIMIT=-1 composer install
  

  This method is often preferred as it's specific to Composer's operation and doesn't affect other PHP CLI scripts unless they're part of the Composer execution.

2. Locating Your PHP CLI Configuration File (php.ini)

For a permanent solution, you need to modify the php.ini file that governs the PHP CLI environment.

First, identify which php.ini file is being loaded by the CLI:

php --ini

The output will show the "Loaded Configuration File" and additional "Scan for additional .ini files in" directories. On Ubuntu 22.04 LTS, with PHP 8.1 (the default for 22.04), the primary CLI configuration file is typically:

/etc/php/8.1/cli/php.ini

If you have multiple PHP versions installed (e.g., PHP 8.2, 8.3), ensure you're editing the php.ini for the version Composer is using. You can check Composer's PHP version with composer diagnose.

3. Permanently Increasing PHP CLI memory_limit

Edit the identified php.ini file using your preferred text editor (e.g., nano, vim).

sudo nano /etc/php/8.1/cli/php.ini

Search for the memory_limit directive (usually near the "Resource Limits" section). It might look like this:

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

Change the value to a more suitable amount. For most large projects, 512M or 1G is a good starting point. Extremely large projects might even require 2G.

memory_limit = 1G

Choose a value appropriate for your server's available RAM. Setting memory_limit too high on a server with limited physical memory can lead to the Linux OOM (Out Of Memory) killer terminating processes, including critical system services. Start with 512M or 1G and increase if necessary.

Save the file and exit the editor. Changes to the PHP CLI php.ini generally take effect immediately without needing to restart services, as the CLI process starts and stops with each command.

4. Verifying the New memory_limit

To confirm your change, run the following command:

php -r "echo ini_get('memory_limit');"

The output should reflect the new memory_limit you set (e.g., 1G).

Now, retry your Composer command:

composer install

or

composer update

5. (Optional) Adjusting PHP-FPM memory_limit (for web applications)

While the Composer error specifically relates to the PHP CLI, it's important to understand that PHP-FPM (FastCGI Process Manager) uses a separate php.ini file. If your web application also experiences memory-related errors (e.g., "Allowed memory size exhausted" in web server error logs), you'll need to adjust the FPM configuration as well.

The PHP-FPM php.ini is typically located at:

/etc/php/8.1/fpm/php.ini

Edit this file:

sudo nano /etc/php/8.1/fpm/php.ini

Locate the memory_limit directive and set it to an appropriate value, similar to the CLI.

memory_limit = 512M

When modifying PHP-FPM settings, you must restart the PHP-FPM service for changes to take effect.

sudo systemctl restart php8.1-fpm

No Nginx or Apache restart is typically needed for PHP configuration changes, as they communicate with PHP-FPM via a socket.

6. Optimizing Composer Usage (Best Practices)

Beyond increasing memory, adopting good Composer practices can reduce memory strain.

• Keep Composer Up-to-Date: Regularly update Composer to benefit from performance improvements and bug fixes.

  composer self-update --stable
  

• Use --no-dev in Production: When deploying to production, avoid installing development dependencies. This significantly reduces the number of packages Composer needs to process.

  composer install --no-dev --optimize-autoloader
  

• Prioritize install over update: composer install uses the composer.lock file, which is faster and less memory-intensive as it doesn't need to resolve new dependencies. composer update performs a full dependency resolution, which is more resource-intensive.
• Clear Composer Cache: Occasionally, a corrupted or very large cache might contribute to issues (though less directly to memory limits).

  composer clear-cache
  

By following these steps, you should successfully resolve the "Composer Memory Limit Exhausted" error on your Ubuntu 22.04 LTS system, enabling smooth PHP package management.