How do I remove a submodule in Git?

Removing a submodule takes three commands and a commit. Deleting the folder by hand is not enough: Git keeps a record of the submodule in your repository and in .git/modules, and leaving either behind causes confusing errors later.

For background on how submodules work, see the git submodule command reference.

Remove a submodule

Assume the submodule lives at vendor/lib. Run these from the root of the main repository:

git submodule deinit -f vendor/lib
git rm -f vendor/lib
rm -rf .git/modules/vendor/lib
git commit -m "Remove vendor/lib submodule"

What each step does:

  1. git submodule deinit -f vendor/lib unregisters the submodule and empties its working folder. The -f flag discards any uncommitted changes inside the submodule, so commit or copy out anything you need first.
  2. git rm -f vendor/lib removes the submodule from the index and deletes its folder. It also removes the entry from .gitmodules and stages that change, so you do not need to edit the file yourself.
  3. rm -rf .git/modules/vendor/lib deletes the submodule's stored Git data. Git does not do this for you, and leaving it behind can break a later attempt to add a submodule at the same path.
  4. git commit records the removal.

Check what you are about to commit with git status. You should see .gitmodules modified and vendor/lib deleted, and nothing else.

Push the commit when you are ready:

git push

Check it worked

git submodule status
ls .git/modules

git submodule status should no longer list the path, and .git/modules should not contain a folder for it. If you removed your only submodule, .gitmodules will now be empty.

What changes for deployments

Once the commit is pushed, a deployment from that branch no longer fetches the submodule, and the folder will not be created on your server. If your code still expects files from the old path, deploy a change that provides them another way, such as a package manager dependency or the files copied into the repository.

Submodule problems often show up first as a failed deployment. Our guide to submodule errors during deployment covers the most common ones, including a path that exists in the index but not in .gitmodules.

Quick reference

Goal Command
Unregister the submodule git submodule deinit -f <path>
Remove it from the repository git rm -f <path>
Delete its stored Git data rm -rf .git/modules/<path>
Record the removal git commit -m "Remove <path> submodule"

Need your servers to follow the repository as it changes? DeployHQ deploys your code automatically whenever you push.