How to remove globally a package from Composer?
When you execute composer global require to install tools like PHPUnit, PHPUnit itself, or any other command-line utility into your system environment, those binaries land in a specific directory defined by the bin-dir configuration. By default, this is usually ~/.composer/vendor/bin. While installing globally allows you to run commands from anywhere in the terminal without needing to specify paths, it also means those packages persist until explicitly removed.
To uninstall PHPUnit globally after having installed it via the command composer global require 'phpunit/phpunit=3.7.*', you use the corresponding global remove command. The syntax mirrors the install command but utilizes the global remove flag instead. You would execute:
composer global remove phpunit/phpunit
This single line tells Composer to locate the package in the global vendor directory and delete both the library files and the executable binary. If the removal succeeds, the command outputs confirmation that the package has been removed from the ~/.composer/vendor repository. You can verify this by checking if the phpunit executable still exists in your shell's PATH or by running which phpunit (on macOS/Linux) to ensure it no longer resolves.
It is critical to understand what gets deleted and what remains. Removing a global package does not affect projects that depend on PHPUnit installed locally within their own directories. A project might have its own vendor/bin/phpunit installed via composer install or composer update, completely independent of your system-wide installation. Global packages are meant for tools you use directly from the terminal, whereas local packages belong strictly to the specific project's dependency graph.
One common pitfall arises when dealing with versioned global packages. If you previously installed a specific version like 3.7.* and later upgraded it globally to 9.6.*, simply running the remove command will delete the current version residing in your vendor folder. However, if you have multiple versions cached or if you are unsure which version is currently active, Composer will remove whatever is present in that slot. You do not need to specify a version number when removing, as Composer only cares about the package name and its current state in the global repository.
Another consideration is the vendor/bin directory itself. Sometimes, after removing a global package, you might notice other binaries left behind if they were added manually or via scripts. However, standard global removal cleans up the specific entry point associated with that package. If your environment relies heavily on global tools and you find yourself constantly cleaning up, it is often worth reviewing your composer.json in your home directory (if one exists) to see if any configuration overrides are affecting where binaries are installed.
There is also the nuance of how Composer handles the global repository cache. While removing a package clears the actual files from your system vendor directory, the metadata regarding that removal stays consistent with Composer's internal state. If you attempt to install the same version immediately after removal, Composer will treat it as a fresh install, fetching new dependencies as needed. This behavior ensures that your global environment remains clean and that no "orphaned" versions linger in memory or disk space unless explicitly re-added.
For developers managing complex environments where global tools might conflict with local ones, keeping these distinctions clear prevents subtle bugs. For instance, a script expecting PHPUnit 3.7 globally but finding a different version locally could fail if not properly scoped. Understanding the global remove command allows you to correct these mismatches or entirely strip the global environment of unused tools, returning your shell to a state where only explicitly required tools are available.
