How to install PHP composer inside a docker container
When setting up a development environment for Laravel using Docker, you often encounter a specific friction point: Composer isn't installed by default in standard PHP images, even when docker-php-ext-install and similar commands successfully add extensions like imagick or mcrypt. If your application relies on composer dump-autoload to refresh class maps after running database migrations, the absence of Composer will cause the build process to fail immediately.
A common approach involves appending a command to your Dockerfile to install the tool:
RUN curl -sS https://getcomposer.org/installer | php -- \
--install-dir=/usr/bin --filename=composer
This command downloads the installer script and executes it, placing a binary named composer directly into /usr/bin. Since /usr/bin is part of the standard system PATH, this method should theoretically work. However, many developers report encountering the error exec: "composer": executable file not found in $PATH when running docker-compose exec app composer dump-autoload.
This discrepancy often stems from how Docker Compose constructs the runtime environment or how the specific PHP base image manages its internal PATH. While placing the binary in /usr/bin is generally correct for Alpine-based images, it can sometimes be inconsistent with Debian-based images (like the php:7.1.3-fpm example provided) if the container's default shell environment doesn't explicitly source the system binaries into the active path during execution.
To resolve this, you have two primary strategies depending on your desired level of isolation and portability.
Explicitly Setting the PATH in the Dockerfile
The most robust solution is to ensure Composer is installed in a location that aligns perfectly with the image's default PATH or to explicitly modify the environment variable within the container. If you prefer keeping the binary in /usr/bin, you can add a step to refresh the environment or, more commonly, move the installation target to a standard bin directory if one exists, though modifying the PATH is the direct fix for existing installations.
You can update your Dockerfile to explicitly set the PATH after installing Composer:
RUN curl -sS https://getcomposer.org/installer | php -- \
--install-dir=/usr/bin --filename=composer && \
PATH="/usr/bin:${PATH}" && \
docker-php-ext-install mcrypt pdo_mysql imagick
While the && operator chains commands, simply appending to the PATH inside the same layer ensures that any subsequent steps or entrypoints inherit this configuration. However, a more persistent fix is often required if the default entrypoint script resets the environment.
Installing Composer into the User Directory
An alternative approach that frequently circumvents these path resolution issues is installing Composer globally into the application user's home directory. This method avoids reliance on system-level PATH configurations which can vary between base images.
You can modify your installation command to target a specific directory, such as /home/app/.composer, and then update your shell profile or environment variable:
RUN curl -sS https://getcomposer.org/installer | php -- \
--install-dir=/home/app/.composer --filename=composer
ENV PATH="/home/app/.composer:${PATH}"
By setting the PATH environment variable in the same layer, you guarantee that any process spawned from that imageâincluding your Laravel applicationâwill locate the binary. This approach is particularly useful when dealing with multi-stage builds or when the base image has a restrictive default configuration.
Verifying the Installation
Once you have rebuilt your image with one of these modifications, verify the installation before running migrations. You can check if the command resolves correctly by inspecting the container:
docker-compose exec app which composer
If this returns a valid path (e.g., /usr/bin/composer), the issue is resolved. If it returns nothing, you must revisit your Dockerfile to ensure the PATH variable was set in a way that persists across the container's lifecycle. Remember that docker-compose exec runs commands as the default user defined in your docker-compose.yml, so ensuring the binary is accessible to that specific user context is also critical.
For more complex setups involving multiple services or shared volumes, consider checking if your application entrypoint script overrides the shell environment. In some cases, explicitly setting PATH in your docker-compose.yml under the service definition can be a faster workaround than modifying the base image:
environment:
- PATH=/usr/bin:${PATH}
However, embedding this directly into the Dockerfile is generally preferred for reproducibility and cache efficiency.
