Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

The shell cannot find the composer command

Errorcomposer: command not found

Short answer

The shell found no file named composer in any folder on your PATH. Either Composer was never installed globally, or its file sits in a folder that PATH does not list, or you changed PATH in a terminal that was already open. Locate the file, move it into a PATH folder, and open a new terminal.

  • Applies to Composer 2, PHP 8.3, Ubuntu 24.04, macOS, Windows 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the shell what it sees, then look for a downloaded composer.phar. The two results show which cause below you have.

    command -v composer
    echo "$PATH" | tr ':' '\n'
    ls composer.phar ~/.local/bin/composer /usr/local/bin/composer
  2. 2Match what you see, then jump to its fix

    1. 1command -v prints nothing, and no composer or composer.phar file exists in the places aboveComposer was never installed globallyFix
    2. 2ls finds composer in a folder that the PATH listing does not showThe file exists, but not in a folder on PATHFix
    3. 3mv fails with /usr/local/bin/composer: No such file or directoryOn macOS, /usr/local/bin does not existFix
    4. 4composer is not recognized right after install or after editing PATHOn Windows, PATH was changed but the terminal is oldFix

What does the error look like?

  • composer: command not found
  • bash: composer: command not found

Cause 1 of 4

Composer was never installed globally

1Check

Running php composer.phar from the project folder works only if you downloaded the file there. A global command needs the file in a PATH folder.

php -v && php composer.phar --version

2Fix

Download Composer with the installer on the official download page, then move the file to a folder on PATH under the name composer. Use sudo if the move fails on permissions.

sudo mv composer.phar /usr/local/bin/composer

3Verify

Open a new terminal and print the version.

composer --version

Confirmed by getcomposer.org

Did this fix it?

Cause 2 of 4

The file exists, but not in a folder on PATH

1Check

Compare the folder holding the file with the PATH lines printed above. A per-user folder such as ~/.local/bin is on PATH only on some distributions.

ls -l ~/.local/bin/composer
echo "$PATH" | tr ':' '\n' | grep -n ".local/bin"

2Fix

Move the file to a folder that is on PATH, or add its folder to PATH in your shell profile (for example ~/.bashrc or ~/.zshrc).

export PATH="$HOME/.local/bin:$PATH"

3Verify

Open a new terminal, then confirm which file the shell uses.

command -v composer

Confirmed by getcomposer.org

Did this fix it?

Cause 3 of 4

On macOS, /usr/local/bin does not exist

1Check

Some macOS versions have no /usr/local/bin folder, so the move target is invalid.

ls -ld /usr/local/bin

2Fix

Create the folder first, then move the file.

sudo mkdir -p /usr/local/bin
sudo mv composer.phar /usr/local/bin/composer

3Verify

Run the version command from any folder.

cd ~ && composer --version

Confirmed by getcomposer.org

Did this fix it?

Cause 4 of 4

On Windows, PATH was changed but the terminal is old

1Check

PATH is read when a terminal starts, so an open window keeps the old value. A manual install also needs a composer.bat next to composer.phar.

where composer
echo %PATH%

2Fix

Close the terminal and open a new one. With a manual install, make composer.bat contain the line below and keep its folder on PATH. The Composer-Setup.exe installer does both steps for you.

@php "%~dp0composer.phar" %*

3Verify

In the new terminal, print the version.

composer -V

Confirmed by getcomposer.org

Did this fix it?

How do I stop it coming back?

  • Install Composer once, globally, with the official installer and keep the file in a folder that is on PATH.
  • After any PATH change, open a new terminal before you test it.
  • In CI and Docker, copy the file to /usr/local/bin/composer in the image build instead of calling php composer.phar from a random folder.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

CodeIgniter 4 cannot write its cache files

CodeIgniter\Cache\Exceptions\CacheException: Cache unable to write to /var/www/app/writable/cache/

CodeIgniter 4's file cache needs a cache directory that the web server can really write to.

2 causes, each with a fix

Back end

CodeIgniter 3 loads the model but the property is undefined

The model name you are loading is the name of a resource that is already being used: user

CodeIgniter 3 expects a model file named like its class, with the first letter capitalised, for example User_model.php holding class User_model.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.