How Can I Delete a Remote Tag?
Git tags mark specific points in your repository history, typically used for releases like v1.0.0 or v2.1.3. Sometimes you need to delete a tag - maybe you tagged the wrong commit, used an incorrect version number, or need to recreate a release. While deleting a local tag is straightforward, removing a tag from a remote repository requires an additional step that isn't immediately obvious.
TLDR
To delete a remote tag, use git push origin --delete tagname or the alternative syntax git push origin :refs/tags/tagname. To also delete the local tag, run git tag -d tagname. Always coordinate with your team before deleting tags that others might be using.
Prerequisites
You need a Git repository with tags and push access to the remote repository. Basic familiarity with Git commands and understanding of what tags are will help you follow along.
Understanding Local vs Remote Tags
When you create a tag locally, it exists only in your local repository until you explicitly push it:
# Create a local tag
git tag v1.0.0
# List local tags
git tag
To make the tag available to others, push it:
# Push a specific tag
git push origin v1.0.0
# Or push all tags at once
git push --tags
Once pushed, the tag exists in two places - your local repository and the remote repository. Deleting a local tag doesn't automatically delete the remote tag, and vice versa. You need to delete them separately.
Deleting a Remote Tag
The standard way to delete a remote tag is:
git push origin --delete v1.0.0
This tells Git to delete the tag v1.0.0 from the remote named origin. You'll see output like:
To github.com:username/project.git
- [deleted] v1.0.0
An alternative syntax that does the same thing:
git push origin :refs/tags/v1.0.0
This older syntax means "push nothing to the remote tag v1.0.0", which effectively deletes it. The modern --delete flag is clearer and preferred, but both work identically.
Deleting Both Local and Remote Tags
To completely remove a tag from both local and remote:
# Delete the local tag
git tag -d v1.0.0
# Delete the remote tag
git push origin --delete v1.0.0
You can run these in either order. If you delete the remote tag first, the local tag remains in your repository but won't be on the remote anymore.
Deleting Multiple Remote Tags
To delete several tags at once:
# Delete multiple tags from remote
git push origin --delete v1.0.0 v1.0.1 v1.0.2
# Delete local tags
git tag -d v1.0.0 v1.0.1 v1.0.2
For many tags, you might script it:
# Delete all tags matching a pattern from remote
for tag in $(git tag -l "v1.0.*"); do
git push origin --delete $tag
done
# Delete matching local tags
git tag -d $(git tag -l "v1.0.*")
This example deletes all tags starting with v1.0. - useful when cleaning up a series of pre-release tags or correcting a versioning mistake.
Verifying Tag Deletion
After deleting a remote tag, verify it's gone:
# List all remote tags
git ls-remote --tags origin
# Or fetch the latest tag info
git fetch --tags --prune
The --prune flag removes references to tags that no longer exist on the remote. Without it, your local Git might still show remote tags that have been deleted.
Check your local tags:
# List all local tags
git tag
# Search for a specific tag
git tag -l "v1.0.0"
Handling Permission Issues
If you get a permission error when deleting a remote tag:
error: unable to delete 'v1.0.0': remote ref does not exist
error: failed to push some refs to 'github.com:username/project.git'
This could mean:
- The tag doesn't exist on the remote: Check with
git ls-remote --tags origin - You don't have permission: Some repositories protect tags, especially in production environments
- The tag is protected: Platforms like GitHub and GitLab allow protecting tags to prevent accidental deletion
For protected tags, you may need to:
- Temporarily unprotect the tag in your Git hosting platform's settings
- Ask someone with appropriate permissions to delete it
- Use your Git host's web interface to delete the tag
Recreating a Tag After Deletion
A common workflow is deleting and recreating a tag, perhaps because you tagged the wrong commit:
# Delete the incorrect tag locally and remotely
git tag -d v1.0.0
git push origin --delete v1.0.0
# Create the tag on the correct commit
git checkout main
git tag v1.0.0
# Push the corrected tag
git push origin v1.0.0
Or create the tag on a specific commit:
# Delete old tag
git tag -d v1.0.0
git push origin --delete v1.0.0
# Create tag on specific commit
git tag v1.0.0 abc123def
# Push the new tag
git push origin v1.0.0
Impact on Team Members
When you delete a remote tag, it doesn't automatically disappear from your teammates' local repositories. They'll still have the old tag locally until they prune:
# Team members should run this to sync tags
git fetch --tags --prune
This updates their local tag references to match the remote, removing tags that no longer exist remotely.
Important: Coordinate with your team before deleting tags. If someone has deployed code using a specific tag, deleting it can cause confusion. If the tag is referenced in documentation, CI/CD pipelines, or deployment scripts, those references will break.
Tags in Release Management
In production environments, tags typically represent releases. Deleting them should be done carefully:
Pre-release tags (like v1.0.0-beta.1 or v1.0.0-rc.1) can usually be deleted safely if you're still iterating.
Production release tags (like v1.0.0 or v2.3.1) should rarely be deleted. If a release had problems:
# Instead of deleting v1.0.0, create v1.0.1 with fixes
git tag v1.0.1
git push origin v1.0.1
This preserves the history and makes it clear that 1.0.1 supersedes 1.0.0.
Recovering a Deleted Tag
If you accidentally delete a tag before pushing the deletion, you can recover it from your reflog:
# Find the commit that was tagged
git reflog | grep "v1.0.0"
# Recreate the tag on that commit
git tag v1.0.0 <commit-hash>
However, if the tag has been deleted from both local and remote and you don't have it in your reflog, you'll need to recreate it on what you believe was the correct commit. This is why it's important to be certain before deleting tags, especially release tags.
Deleting Tags on Different Git Platforms
GitHub
You can delete tags via the web interface:
- Go to your repository's Releases page
- Find the release associated with the tag
- Click Edit or Delete
- Delete the release (this doesn't delete the tag automatically)
- Go to the Tags page and delete the tag
Or use the command line as shown above.
GitLab
GitLab's interface:
- Navigate to Repository → Tags
- Click the delete icon next to the tag
Or use command line.
Bitbucket
Bitbucket interface:
- Go to the repository
- Click on Tags in the navigation
- Click the delete icon next to the tag
Command line works the same across all platforms.
Scripting Tag Cleanup
For automated tag cleanup, you might create a script:
#!/bin/bash
# Delete old pre-release tags
# Get all tags matching pattern
OLD_TAGS=$(git tag -l "*-beta*" "*-alpha*" "*-rc*")
if [ -z "$OLD_TAGS" ]; then
echo "No pre-release tags to delete"
exit 0
fi
echo "Found pre-release tags:"
echo "$OLD_TAGS"
read -p "Delete these tags? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
for tag in $OLD_TAGS; do
echo "Deleting $tag..."
git tag -d "$tag"
git push origin --delete "$tag"
done
echo "Done!"
else
echo "Cancelled"
fi
This script finds all alpha, beta, and release candidate tags, shows them to you, and asks for confirmation before deleting.
Best Practices for Tag Management
Use semantic versioning: Follow a consistent versioning scheme (like SemVer: major.minor.patch) so tags are predictable.
Protect production tags: Configure your Git hosting platform to protect release tags from accidental deletion.
Document deletions: If you must delete a production tag, document why in your team's communication channels.
Create annotated tags for releases: Use git tag -a v1.0.0 -m "Release 1.0.0" instead of lightweight tags. Annotated tags include metadata about who created the tag and when.
Automate where possible: Use CI/CD tools to create tags automatically based on successful builds or deployments.
Never reuse tag names: If you delete a tag, don't recreate it with the same name pointing to a different commit. This causes confusion. Instead, increment the version number.
Deleting remote tags is straightforward once you know the command, but the decision to delete should be made carefully. Tags serve as important markers in your project's history, and removing them can impact deployments, documentation, and team workflows. When in doubt, it's usually better to create a new tag with an incremented version than to delete and recreate an existing one.
Found an issue?