HullsparkHow to merge duplicate labels in Confluence
how-to, how_to and howto are three different labels, so a label search finds only some of your pages. Confluence Cloud has no merge for labels. Here is the built-in way, where it stops, and one option.
Hullspark · updated 2026-10-29
Short answer
- Merge: Atlassian's label documentation describes adding and removing labels on a page. It describes no merge and no rename [1].
- Find the variants: the site-wide list of labels is at
/wiki/labels/listlabels-alphaview.actionon your site [1]. - Workaround: on each page, add the label you keep, then remove the old one.
- Remove a label from the whole site: you remove it from every page, live doc and attachment where it appears [1].
What Confluence gives you out of the box
| Tool | Good for | Catch |
|---|---|---|
| Label list (one space or the whole site) | Seeing every label, and a word cloud under Popular Labels [1] | A list to read. It is not a place to rename or merge, and the documentation does not mention page counts |
| Details panel on a page | Anyone who can edit a page can add labels with +, and the x next to a label removes it [1] | One page at a time. A page you cannot edit stays as it is |
| Labels on a template | New pages made from the template get its labels automatically [1] | Helps new pages only. Pages that already exist are not changed |
Doing it by hand
- Open the site label list and write down the labels that mean the same thing. Use
https://your-site.atlassian.net/wiki/labels/listlabels-alphaview.action[1]. - Pick one spelling for each group. Labels are lower case and cannot contain spaces; Confluence turns a space into a hyphen [1], so typing “how to” already gives how-to.
- Open each old label from the list to see the pages that carry it.
- On each of those pages or live docs, open Details, add the label you picked with +, then remove the old one with its x [1].
- Repeat for attachments that carry the old label: in Details, open the arrow next to Files and use the edit icon in the Labels column [1].
- Check the list again. A label can stay in the list while deleted pages that carry it sit in a space trash, because deleted content can keep its labels until the trash is purged [1].
- If one team keeps creating a variant, fix the template that adds it [1].
Where the built-in way stops
- One page at a time. A label on 300 pages means 300 edits.
- No merge, no rename. The documentation describes neither, so every change is an add plus a remove.
- No safety net. The documentation describes no preview and no record of what you changed.
- Pages you cannot edit. They keep the old label until someone with edit rights changes them.
One option: our own app
I make a Confluence Cloud app for this, Label Sweep by Hullspark [2]. What it does, as the current code and the product page describe it:
- One list of likely duplicates. Labels that differ only by singular and plural (English words) or by hyphen, underscore or no separator are grouped, with usage counts and a suggested label to keep. These are suggestions; you decide.
- Merge a group. Merge this group… fills in the merge form and starts a dry run. You can also tick up to 50 labels in the list and press Merge into one…, which merges them into the most used one.
- Dry run first. The dry run lists what will change. Nothing changes until you press Run. The confirmation names the change, says how many items it touches and says plainly that it cannot be undone.
- Safe on interruption. Each page is processed as add the new label, then remove the old one, so a job that stops partway may leave a page with both labels but never without one. Press Resume to continue. The Jobs tab keeps a log.
- Rename and delete work the same way, with the same dry run.
It covers pages and blog posts with global labels. Attachment labels and space labels are not handled yet. Starting or resuming a change needs a Confluence administrator. A job runs with the permissions of that person, so pages they cannot edit are not changed. Without a license the app is read-only: listing, search and dry run work.
See it on the Atlassian Marketplace Product page
Questions
Can Confluence merge two labels?
Not in Atlassian's label documentation. It describes adding and removing labels page by page, and does not describe a merge or a rename.
Does Label Sweep find duplicates by itself?
It groups labels that differ only by singular and plural (English words) or by hyphen, underscore or no separator. It only suggests.
Can I undo a merge?
No. The confirmation says so, which is why the dry run comes first. Read it before you press Run.
What if a job stops halfway?
Each page gets the new label first and then loses the old one, so an interrupted page may briefly carry both labels but never loses one. Press Resume and the job continues where it stopped.
Does it change attachment labels or space labels?
No. It covers pages and blog posts with global labels.
Does my data leave Atlassian?
No. The app runs on Atlassian. Details are in the privacy policy.
Do I need a license to look?
No. Listing, search and the dry run work without one. Rename, Merge and Delete need an active license and a Confluence administrator. The Marketplace listing has the current pricing.
What I have not verified
I checked the Confluence claims on this page against Atlassian's label documentation on 2026-10-29. I did not re-test each one on a live site, and Atlassian changes screens.
I did not confirm that opening a label from the list shows its pages in every version of Confluence. The app description comes from its current code and product page. I have not tested other vendors' apps and name none; read their listings.
Sources
- [1] Atlassian Support: Use labels to organize your content: https://support.atlassian.com/confluence-cloud/docs/use-labels-to-organize-your-content/
- [2] Atlassian Marketplace listing of the app (fetched 2026-10-29): https://marketplace.atlassian.com/apps/682622877
Related
- Label Sweep for Confluence: screenshots and FAQ
- Getting started with Label Sweep: your first merge in four steps
- All English guides
Questions? Support or support@hullspark.com. Privacy policy