How to Install Composer on Arch Linux

Most modern PHP projects expect Composer before the first framework, package, or autoloader step works. To install Composer on Arch Linux, use the official composer package from Arch’s extra repository instead of the upstream installer script; pacman then owns the composer command, the PHP dependency, and future updates.

Composer resolves packages from Packagist, writes project requirements to composer.json, locks exact dependency versions in composer.lock, and generates the vendor/autoload.php file that PHP applications load at runtime.

Update Arch Linux Before Installing Composer

Synchronize package databases and upgrade installed packages before installing Composer. Arch is a rolling release distribution, and a full update avoids partial-upgrade dependency conflicts:

sudo pacman -Syu

These commands use sudo for tasks that need root privileges. If your user is not in the sudoers file yet, run the commands as root or follow the guide on how to add and manage sudo users on Arch Linux.

Install Composer on Arch Linux with pacman

The Arch package database lists composer in the official extra repository, and the Arch Wiki PHP page documents Composer as part of the PHP toolchain. The package depends on php and unzip, so pacman installs those dependencies automatically when they are not already present:

sudo pacman -S composer

Confirm the package and its main runtime dependencies are installed. Version numbers change with Arch’s rolling repositories, so focus on the package names and installed-state proof:

pacman -Q composer php unzip

Relevant output includes:

composer 2.x.x-1
php 8.x.x-1
unzip 6.0-23

Verify that the composer command comes from the pacman package:

command -v composer
pacman -Qo /usr/bin/composer

Expected output:

/usr/bin/composer
/usr/bin/composer is owned by composer 2.x.x-1

Check Composer and PHP from the same shell:

composer --version
php --version

Relevant output starts like this, with point releases and build dates varying over time:

Composer version 2.x.x [date/time]
PHP 8.x.x (cli) (built: [build date]) (NTS)

Configure Composer Global Tools on Arch Linux

Composer can install command-line tools globally for your user account. On Arch, the global Composer home resolves to ~/.config/composer, and global package binaries live under ~/.config/composer/vendor/bin.

Print the exact global binary directory for your account:

composer global config bin-dir --absolute

Example output:

/home/your-user/.config/composer/vendor/bin

Add that directory to Bash with a rerun-safe line in ~/.bashrc:

grep -qxF 'export PATH="$HOME/.config/composer/vendor/bin:$PATH"' ~/.bashrc || printf '\nexport PATH="$HOME/.config/composer/vendor/bin:$PATH"\n' >> ~/.bashrc
source ~/.bashrc

If you use Zsh, apply the same line to ~/.zshrc and reload it with source ~/.zshrc. The path is per user, so repeat this only for accounts that need global Composer tools.

Install a global Composer tool to confirm the path works. This example uses PHP_CodeSniffer, a small CLI tool that exposes the phpcs command:

composer global require squizlabs/php_codesniffer
phpcs --version
composer global show --name-only

Relevant output includes:

PHP_CodeSniffer version 4.x.x (stable) by Squiz and PHPCSStandards
squizlabs/php_codesniffer

Create a PHP Project with Composer on Arch Linux

Composer works per project by reading composer.json, installing dependencies into vendor/, and writing exact resolved versions to composer.lock. The following example creates a small project and adds Monolog from Packagist.

Initialize a New Composer Project

Create a project directory and initialize Composer inside it:

mkdir ~/my-php-project
cd ~/my-php-project
composer init --name="vendor/my-project" --description="A sample PHP project" --type=project --license=MIT --no-interaction

Expected output:

Writing ./composer.json

View the generated file:

cat composer.json

{
    "name": "vendor/my-project",
    "description": "A sample PHP project",
    "type": "project",
    "license": "MIT",
    "require": {}
}

Add a Package Dependency with Composer

Use composer require to add a package from Packagist. This example installs Monolog, a common PHP logging library:

composer require monolog/monolog

Use the same command shape for other packages, such as guzzlehttp/guzzle, dompdf/dompdf, endroid/qr-code, or drush/drush. Do not use composer install vendor/package to add a new package; composer install reads an existing composer.lock file.

Composer updates composer.json, writes a composer.lock file, and downloads package code under vendor/. List package names to confirm the dependency tree:

composer show --name-only

Expected output:

monolog/monolog
psr/log

Test the Composer Autoloader

Create a file named test.php in the project directory with this PHP code:

<?php
require __DIR__ . '/vendor/autoload.php';

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('app');
$log->pushHandler(new StreamHandler('app.log', Logger::WARNING));
$log->warning('This is a test warning');

if (is_file(__DIR__ . '/app.log')) {
    echo "Composer autoload loaded Monolog\n";
}

Run the script from the same project directory:

php test.php

Expected output:

Composer autoload loaded Monolog

The script also creates app.log in the project directory, which proves the installed package loaded through vendor/autoload.php.

Manage Composer Dependencies on Arch Linux

Composer itself stays package-managed through pacman. Project dependencies stay inside each project directory and are managed with Composer commands.

Update Composer Itself with pacman

Update the Arch Composer package through normal system upgrades:

sudo pacman -Syu

Do not use composer self-update for the pacman-installed Composer package. That command targets upstream PHAR updates and can bypass pacman’s file ownership under /usr/bin/composer.

Install Dependencies from composer.lock

When cloning an existing project or deploying a known dependency set, use composer install. This reads composer.lock and installs the exact versions already resolved by the project:

composer install

For production deployments, skip development-only packages and optimize the autoloader:

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

Validate Composer Project Metadata

When a project behaves differently across machines, validate composer.json and check the active PHP platform before changing dependency constraints:

composer validate --no-check-publish
composer check-platform-reqs

Relevant output for a healthy project includes valid metadata and successful platform checks:

./composer.json is valid
php 8.x.x   success

Update Composer Project Dependencies

Use composer update during development when you intentionally want newer package versions within the constraints in composer.json:

composer update

Update a single package and any dependencies it needs without refreshing the entire dependency graph:

composer update monolog/monolog --with-dependencies

Commit composer.lock for applications so other machines install the same resolved dependency set. Libraries commonly omit the lock file because downstream projects resolve their own dependency graph.

Remove a Composer Package

Remove a package from the current project with composer remove. Composer updates composer.json, rewrites composer.lock, and removes unused package files from vendor/:

composer remove monolog/monolog

Target a Specific PHP Version with Composer

Some projects need Composer to resolve dependencies as if they will run on a different PHP version than the one currently installed on Arch. Use Composer’s project-level platform setting for dependency resolution:

composer config platform.php 8.3.0
composer config platform.php

Expected output:

8.3.0

Run composer update after changing platform requirements so the lock file reflects the target runtime. This setting changes dependency resolution only; it does not switch the PHP binary that runs Composer. Remove the override when the project no longer needs it:

composer config --unset platform.php

Run Composer with php-legacy on Arch Linux

Arch also packages php-legacy for projects that still need the previous PHP branch. The official Composer package depends on the current php package, so keep that installed and call Composer through php-legacy only for the specific project command that needs it:

sudo pacman -S php-legacy
php-legacy /usr/bin/composer --version

Relevant output includes:

Composer version 2.x.x [date/time]
PHP version 8.3.x (/usr/bin/php-legacy)

Troubleshoot Composer on Arch Linux

Composer Command Not Found After Installation

If the shell returns this error after installation, check package state and the binary path:

bash: composer: command not found
zsh: command not found: composer

pacman -Qi composer
command -v composer
pacman -Qo /usr/bin/composer

A healthy pacman install returns /usr/bin/composer and reports that the file is owned by the composer package. If pacman -Qi composer reports that the package is not installed, install it again:

sudo pacman -S composer

Composer Global Tool Command Not Found

If composer works but a global tool such as phpcs does not, the Composer global bin directory is probably missing from your shell PATH. Reprint the directory and check your current PATH:

composer global config bin-dir --absolute
printf '%s\n' "$PATH"

If the global bin directory is absent, repeat the PATH setup from the global tools section, then open a new terminal or reload your shell configuration.

Composer SSL Certificate Error

Older Composer installer-script instructions can fail with SSL errors like this:

The Composer installer script was not successful [exit code 1].
The "https://getcomposer.org/versions" file could not be downloaded: SSL operation failed

On Arch, the package-managed path avoids the upstream installer script entirely. Refresh the system trust store package and run Composer’s diagnostics:

sudo pacman -Syu ca-certificates
composer diagnose

The Packagist connectivity lines should report OK:

Checking http connectivity to packagist: OK
Checking https connectivity to packagist: OK

If Composer reports that SSL/TLS protection is disabled, re-enable TLS and require secure package URLs before running another install or update:

Composer is configured to disable SSL/TLS protection. This will leave remote HTTPS requests vulnerable to Man-In-The-Middle attacks.

composer config --global disable-tls false
composer config --global secure-http true
composer diagnose

The connectivity checks should return to OK after TLS is enabled and the system trust store is current.

On a normal Arch PHP configuration, openssl.cafile can show no value while Composer HTTPS still works because OpenSSL can use the system trust store:

php -i | grep -E 'openssl.ca(file|path)'

Example output from a working Arch system:

openssl.cafile => no value => no value
openssl.capath => no value => no value

Edit /etc/php/php.ini only when your local configuration points to a broken custom CA file or Composer still reports HTTPS failures after the system trust store is current.

Composer Detected PHP Platform Issues

This error means the installed PHP runtime does not satisfy the versions or extensions recorded in the project dependencies:

Composer detected issues in your platform:
Your Composer dependencies require a PHP version ">= 8.6.0".

Check the PHP binary Composer is using and compare it with the project’s platform requirements:

php --version
composer check-platform-reqs

A failed requirement points to the package, extension, or PHP branch that needs attention:

php 8.x.x vendor/my-project requires php (>=8.6) failed

If the project targets an older PHP branch, use php-legacy /usr/bin/composer for that project or set platform.php for dependency resolution as shown earlier. Avoid making --ignore-platform-req=php the normal install path; it bypasses the check but can leave dependencies that cannot run under the active PHP binary.

Composer Dependency Conflict During Update

This error means Composer could not find dependency versions that satisfy every package constraint:

Your requirements could not be resolved to an installable set of packages.

Trace which installed package requires the conflicting dependency. For example, Monolog requires psr/log:

composer why psr/log

Relevant output includes:

monolog/monolog 3.x.x requires psr/log (^2.0 || ^3.0)

If the conflict comes from stale dependencies, update the target package and the dependencies it needs:

composer update monolog/monolog --with-dependencies

If the conflict mentions PHP itself, check whether the project needs a platform.php setting or a real php-legacy runtime as described in the management section.

PHP Memory Limit Exhausted During Composer Operations

Large dependency trees can exhaust PHP’s configured CLI memory limit during composer update:

PHP Fatal error: Allowed memory size of [bytes] exhausted

Remove the limit for one Composer command first:

COMPOSER_MEMORY_LIMIT=-1 composer update

If the project routinely needs more memory, inspect the current CLI value, edit /etc/php/php.ini, and set a larger memory_limit such as 512M:

php -i | grep memory_limit

Remove Composer from Arch Linux

Remove the pacman-managed Composer package and dependencies that are no longer required by other packages:

sudo pacman -Rns composer

The -Rns flags remove the package, unneeded dependencies, and package-owned backup configuration files. If you installed php-legacy only for one legacy project, remove it separately after confirming no other project needs it:

sudo pacman -Rns php-legacy

Verify Composer is no longer installed:

pacman -Qi composer

Expected output:

error: package 'composer' was not found

Pacman does not remove per-user Composer data. Delete your global Composer directory only when you no longer need global tools, cached packages, or authentication tokens such as private-repository credentials:

The following command permanently deletes globally installed Composer packages, cached archives, and any Composer authentication file under ~/.config/composer. Back up credentials such as ~/.config/composer/auth.json before removing the directory.

rm -rf ~/.config/composer

Confirm the per-user Composer home is gone:

if test ! -e ~/.config/composer; then
    echo "composer home removed"
fi

composer home removed

Project-level files such as composer.json, composer.lock, and vendor/ remain inside each project directory. Remove those only from projects you no longer need.

Conclusion

Composer is package-managed on Arch through pacman, with project dependencies isolated in each PHP project and optional global tools available from your user Composer bin directory. For deeper runtime work, install PHP on Arch Linux pairs naturally with this setup, while database-backed applications often need MariaDB on Arch Linux or PostgreSQL on Arch Linux next.