Removing submodules in Git - Commands & Configuration

Introduction

Sometimes you add a submodule to your project but later decide you no longer need it. Removing a submodule requires cleaning up several places in your project to avoid leftover files or broken references.

When a submodule is no longer needed in your project and you want to remove its code and references cleanly.

When you want to reduce your repository size by removing unused submodules.

When a submodule's source repository is deprecated or moved and you want to stop tracking it.

When you want to simplify your project structure by removing nested repositories.

When you accidentally added a submodule and want to undo that addition completely.

Commands

This command removes the submodule's entry from Git's internal configuration and unregisters it, preparing for full removal.

Terminal

git submodule deinit -f path/to/submodule

Expected Output

Cleared directory 'path/to/submodule'

→

-f - Force deinitialization even if the submodule has local changes

This removes the submodule's separate Git repository data stored inside the main repository's .git folder.

Terminal

rm -rf .git/modules/path/to/submodule

Expected Output

No output (command runs silently)

This removes the submodule directory from the working tree and stages the removal for commit.

Terminal

git rm -f path/to/submodule

Expected Output

rm 'path/to/submodule'

→

-f - Force removal even if there are local changes

This commits the removal of the submodule from the repository history.

Terminal

git commit -m "Remove submodule path/to/submodule"

Expected Output

[main abc1234] Remove submodule path/to/submodule

 1 file changed, 0 insertions(+), 0 deletions(-)

 delete mode 160000 path/to/submodule

This deletes any leftover submodule files from your working directory if they still exist.

Terminal

rm -rf path/to/submodule

Expected Output

No output (command runs silently)

Key Concept

If you remember nothing else, remember: removing a submodule requires unregistering it, deleting its Git data, removing its files, and committing these changes.

Common Mistakes

Deleting the submodule folder manually without running git submodule deinit and git rm

This leaves Git still tracking the submodule, causing errors and leftover references.

Always run git submodule deinit and git rm before deleting the folder.

Not removing the submodule's Git data inside .git/modules, causing stale data

Git keeps the submodule's repository data, which can cause confusion or conflicts later.

Remove the submodule's folder inside .git/modules manually after deinit.

Not committing the removal changes, so the submodule still appears in history

Without committing, the removal is not recorded and will reappear on next checkout or clone.

Commit the removal with a clear message after git rm.

Summary

Run git submodule deinit -f to unregister the submodule.

Delete the submodule's Git data inside .git/modules manually.

Use git rm -f to remove the submodule directory and stage the removal.

Commit the removal to record the change in the repository.

Delete any leftover submodule files from your working directory.