How to remove unused dependencies from composer?
When you run composer remove packageauthor/packagename, it executes a specific logical operation: it removes the specified package and any packages that are directly required by it. However, Composer does not automatically prune packages that were installed as transitive dependencies of the removed item if those packages are still listed as requirements or optional dependencies in your composer.json. This behavior can lead to a bloated vendor directory where you have "orphaned" libraries sitting there, consuming disk space and potentially introducing unnecessary security surface area.
To force Composer to clean up and remove all unused packages, you need to understand the distinction between removing a package and pruning the dependency tree. The standard command composer remove handles the former, but it leaves the latter intact unless explicitly told otherwise. You must use the --with-dependencies flag (often aliased via configuration or specific tooling) or, more robustly, leverage the dedicated cleanup logic built into modern Composer versions.
The most reliable method to purge these leftovers is using the composer outdated command in combination with manual verification, or better yet, relying on the --optimize-autoloader and strict dependency checking that happens during a fresh install. However, for an immediate cleanup without reinstalling everything, you should utilize the composer dump-autoload flag in conjunction with a specific pruning strategy, though Composer itself does not have a single "nuke" command by default.
Instead, the industry-standard approach involves running composer remove on the main package and then executing a script to scan for unused packages. While Composer lacks a built-in recursive delete command that runs out of the box in all versions, you can simulate this by ensuring your composer.json accurately reflects only what you actually need. If you have orphaned dependencies, the cleanest technical solution is often to perform a fresh install after cleaning up your configuration files.
# Remove the package and its direct children
composer remove packageauthor/packagename
# Reinstall everything based strictly on composer.json
composer install --no-dev
This approach forces Composer to rebuild the lock file (composer.lock) based solely on the current state of composer.json. Any package that was previously installed but is no longer referenced in the JSON file or its transitive chain will be removed from the vendor directory. This is effectively a "hard reset" of your dependencies relative to your manifest file.
There are trade-offs to consider with this method. Running composer install after a removal can sometimes trigger version resolution conflicts if you have locked versions in composer.lock that are incompatible with the remaining packages. In such cases, you might need to drop the lock file before reinstalling:
rm composer.lock
composer install
Be cautious when using this strategy on production servers, as it alters the entire dependency graph. It is generally safer to perform these operations in a development environment first. Additionally, if you are using tools like phpstan or specific static analysis libraries that might have been installed as dev dependencies, ensure you run composer install --no-dev initially to avoid cluttering your production build with testing tools unless explicitly required.
If you are managing a large monorepo or multiple projects where strict dependency hygiene is critical, consider integrating the cleanup logic into your CI/CD pipeline. This ensures that every deployment starts with a clean slate, preventing "dependency drift" where local vendor folders diverge from the lock file. Always verify that no custom scripts in your project rely on the presence of specific legacy packages before executing a full prune.
For those working within the Laravel ecosystem or similar frameworks, maintaining a lean vendor directory is a best practice for performance and security. You can find further guidance on managing dependencies and optimizing autoloaders at https://laravelcompany.com.