Composer - the requested PHP extension mbstring is missing from your system

Composer - the requested PHP extension mbstring is missing from your system

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

Stefan Bogdanescu

Founder & Senior Architect

Composer - the requested PHP extension mbstring is missing from your system

When you attempt to run composer install or composer require, encountering the error the requested PHP extension mbstring is missing from your system is a common stopper for many developers. This message indicates that the PHP CLI environment used by Composer does not have the Multi-Byte String extension loaded, even if the web server version of PHP has it enabled.

The most frequent source of this confusion lies in the discrepancy between php.ini files. In typical shared hosting or local setups like XAMPP or MAMP, you might be editing a specific php.ini located in the installation directory to remove semicolons and uncomment lines for extensions. However, Composer does not read configuration from these locations by default. Instead, it invokes the PHP binary defined in your system's PATH, which often points to a different executable than the one serving your web application.

To resolve this, you must identify exactly which PHP binary Composer is using and ensure that extension is explicitly loaded. You can verify the active PHP version and location by running:

php -v
which php
# or on Windows
where php

If the output shows a path distinct from your web server configuration (for example, /usr/bin/php versus /var/www/html/php/php.ini), you are likely dealing with two separate PHP installations. The mbstring extension must be enabled for the specific binary Composer invokes.

Once identified, you have three primary options to enable the extension:

  1. Edit the CLI php.ini: Locate the configuration file associated with the binary found in step one (usually via php -i | grep "Loaded Configuration File"). Open that file and ensure the line reads extension=mbstring without a leading semicolon.
  2. Use an ini override: If you lack write permissions to the main config file or want to avoid cluttering it, create a dedicated ini file for CLI usage:
    echo "extension=mbstring" > ~/.php-cli.ini
    export PHP_INI_SCAN_DIR="/home/yourusername/.php-cli.ini"
    
    Alternatively, pass the path directly if your environment supports it: -c /path/to/php.ini.
  3. Reinstall or update PECL: If the extension is missing entirely from the package, you may need to install it via your system's package manager (e.g., sudo apt-get install php-mbstring on Debian/Ubuntu) or use pecl install mbstring if compiling from source.

A specific pitfall occurs when using Docker or containerized environments. If your Dockerfile installs PHP but fails to copy the extension .so file into the standard library path, Composer will fail regardless of the host machine's configuration. In such cases, ensure your base image includes the necessary extensions:

RUN apt-get update && apt-get install -y php-mbstring \
    && docker-php-ext-install mbstring

Another scenario involves using PHP-FPM for your web server while running CLI commands globally. These environments often ship with different modules. For instance, a system might have mbstring enabled for Apache/Nginx but not for the CLI tool because the extension was only compiled against one version or installed via an OS package manager that targets specific services.

If you are working within a Laravel project, specifically using Laravel Forge or Vapor, this error can also appear if the deployment environment lacks the extension. While https://laravelcompany.com often provides robust infrastructure guides for managing these environments, verifying the underlying system configuration remains your responsibility. The platform may handle web server extensions automatically, but CLI tools require explicit attention.

Finally, always check php -m to confirm that mbstring is listed in the active modules. If it is missing from the list despite the extension file existing on disk, the extension might be loaded in a specific SAPI (Application Support Interface) mode only and not globally available for CLI execution. Ensure you are enabling it for the correct interface or using the -d flag in your Composer command as a temporary fix:

composer install -d "extension=mbstring"

This approach bypasses configuration files entirely but is less ideal for long-term stability. The most robust solution is always to ensure the extension is loaded in the global php.ini of the CLI binary you intend to use.

Our network