How to Migrate Confluence Content: Complete Guide (2026)

Migrating Confluence content is something most teams eventually face. Whether you are moving from Confluence Server to Cloud, reorganizing spaces after a company merger, or splitting a monolithic workspace into focused team spaces, the process can feel overwhelming. Pages link to each other, attachments sit deep in page trees, permissions are inherited from parent spaces, and macros pull data from external sources.

This guide walks through the entire Confluence content migration process from start to finish. You will learn how to plan your migration, choose the right tools for your scenario, export and import content without losing data, and validate the result. We cover both Atlassian's built-in export features and the Modern Importer Exporter for Confluence app for format-based migrations.

Common Confluence Migration Scenarios

Before diving into the how-to, it helps to understand the most common reasons teams migrate Confluence content. Each scenario has slightly different requirements:

Server or Data Center to Cloud migration. Atlassian ended Server license sales in February 2024 and stopped supporting Server releases entirely. Many organizations are still mid-migration or planning their move. This is the highest-stakes migration scenario because it involves moving everything — spaces, users, apps, and custom configurations — to a completely different hosting model.

Space reorganization. Teams grow, restructure, and rename departments. A space that once served one team might need to split into three. Pages buried five levels deep in a hierarchy need to move to a flatter structure. This is a content-only migration within the same instance.

Company mergers and acquisitions. When two organizations merge, their Confluence instances often need to consolidate. This typically involves migrating content from one Confluence Cloud instance to another, or bringing an acquired company's Cloud content into the parent instance.

Backup and archival. Not every migration is between live systems. Teams export content for compliance archives, offline review, or disaster recovery. The export format matters here — you want something portable that can be re-imported later.

Format conversion. Sometimes the "migration" is really a format shift: converting Confluence pages to Markdown for a developer wiki, exporting to HTML for a static site, or importing Markdown documentation into Confluence.

Each of these scenarios calls for a different combination of tools and techniques. The step-by-step process below works for all of them, with notes on where to adjust for your specific situation.

Step-by-Step Confluence Content Migration

Step 1: Audit your source content

Before exporting anything, take inventory of what you have. Open your Confluence instance and answer these questions:

• How many spaces need to move? List every space that is in scope for the migration. Include personal spaces if they contain shared project documentation.
• How many pages are in each space? You can find this in Space Settings under Content Tools. Spaces with thousands of pages need special handling — batch them in groups of 50 to 100.
• What attachments exist? Attachments are the most commonly forgotten item in migrations. Count them, check their total file size, and note any unusually large files (videos, databases, high-resolution images).
• What permissions are configured? Document space-level and page-level restrictions. You will need to reapply these after migration since most export tools do not carry permissions over.
• Which pages are stale? Use Confluence's built-in Space Statistics or sort pages by "last modified" date. Pages untouched in over a year are candidates for archival rather than migration.
• What macros and integrations are used? Macros like Jira Issue, Page Properties Report, and third-party macros from marketplace apps may not survive migration intact. Make a list of macro types in use so you can test them after import.

Pro tip: Create a spreadsheet with columns for space name, page count, attachment count, last modified date, key macros, and migration priority. This becomes your migration plan.

Step 2: Choose your migration tool

The tool you choose depends on your migration scenario:

For Server/Data Center to Cloud migration: Use Atlassian's official Confluence Cloud Migration Assistant (CCMA). This is the only supported path for full instance migrations. CCMA handles spaces, users, groups, and app data. It is a server-side tool that runs on your existing Server or Data Center installation.

For space reorganization within the same instance: Use Confluence's built-in space export and import (XML format). Go to Space Settings, then Content Tools, then Export. Choose XML export for full fidelity including page history, or HTML export for a readable snapshot. Then import into the target space.

For cross-instance content migration or format conversion: Use Modern Importer Exporter for Confluence. This app supports export in ADF JSON, ADF XML, and HTML formats, and import from JSON, XML, HTML, and Markdown. It handles bulk operations across multiple spaces and provides progress tracking. For detailed instructions, see the Modern Importer Exporter for Confluence documentation.

For PDF or Word export needs: If your migration target is a document archive rather than another Confluence instance, consider Scroll PDF Exporter or Scroll Word Exporter by K15t for professional document output with templates and branding.

For a full comparison of available tools, see our Import Export for Confluence Compared post.

Step 3: Export content from source

Once you have chosen your tool and audited your content, it is time to export. The exact steps vary by tool, but the general process is the same.

Using Confluence's built-in XML export

1. Navigate to Space Settings for the space you want to export.
2. Go to Content Tools and click Export.
3. Select XML for full fidelity (includes page content, metadata, and attachment references) or HTML for a readable copy.
4. Choose whether to include all pages or a custom selection.
5. Click Export and wait for the download to complete.

The XML export produces a ZIP file containing the space's content in Confluence's internal XML format. This is the best option for importing into another Confluence instance because it preserves the most metadata.

Using Modern Importer Exporter for Confluence

1. Navigate to Apps, then Modern Importer & Exporter for Confluence.
2. On the Export tab, use the Space Selection dropdown to choose one or more source spaces.
3. Browse the content table and select the pages and blog posts you want to export. Use "Select All" for entire spaces, or pick individual pages.
4. Choose your export format:
   • ADF JSON — Best for re-importing to Confluence. Preserves the most formatting and structure.
   • ADF XML — Good for integration with XML-based systems or tools.
   • HTML — Best for viewing in browsers, publishing to static sites, or converting to other formats.
5. Click Export and monitor the progress indicator. Downloads start automatically when complete.
6. For large spaces, break the export into batches of 50 to 100 pages. The app organizes exported files by space in the resulting ZIP archive.

Important: Neither built-in XML export nor Modern Importer Exporter includes attachments in their standard exports. For attachments, use Confluence's built-in space export with the "Include attachments" option, or download attachments separately.

Step 4: Import to target instance

With your exported files ready, import them into the target Confluence instance.

Using Confluence's built-in XML import

1. On the target instance, go to Administration (gear icon), then Import & Export, then Restore.
2. Upload the ZIP file from your XML export.
3. Select the target space or choose to create a new space.
4. Review the import summary and click Import.
5. Wait for the import to complete. Large imports can take several minutes.

Using Modern Importer Exporter for Confluence

1. On the target instance, navigate to Apps, then Modern Importer & Exporter for Confluence.
2. Switch to the Import tab.
3. Upload your export files. The app supports JSON, XML, HTML, and Markdown formats.
4. Select the target space from the dropdown. Make sure you have "Add Page" permission in that space.
5. Choose the import mode:
   • Override — Replaces existing content with the imported version. Use this when you want an exact copy.
   • Append — Adds imported content to the end of existing pages. Use this when merging content.
6. Click Import and monitor the progress. Review success and error counts when the operation completes.
7. For bulk imports, repeat in batches. The app handles conflict resolution by automatically renaming pages with duplicate titles.

For individual page imports: You can also right-click any page or blog post and select Export & Import from the context menu. This is useful for quickly importing content to a specific page without navigating to the bulk import interface.

Step 5: Validate and clean up

After import, thorough validation is critical. Do not skip this step.

Check page hierarchy. Verify that parent-child relationships are intact. Pages should appear in the correct order within the space tree. If pages are flattened or misplaced, move them manually or re-import.

Verify links. Internal links between pages are the most common breakage point in migrations. Open several representative pages and click every link. Links that used absolute URLs (pointing to the old instance) will be broken. Links that used relative paths should still work within the same instance.

Inspect attachments. If attachments were exported separately, verify they are linked correctly to their parent pages. Download a sample of attachments to confirm they open properly.

Test macros. Open pages that use macros — especially Jira Issue macros, Page Properties Report macros, and third-party macros. Check that they render correctly and pull the expected data.

Review formatting. Check tables, code blocks, collapsible sections, and multi-column layouts. These elements sometimes lose formatting during format conversion (for example, when converting HTML back to Confluence's native format).

Reapply permissions. Since permissions are not preserved during export/import, reconfigure space-level restrictions and page-level restrictions based on the documentation from your audit in Step 1.

Update space settings. Check space description, space logo, space color theme, and space sidebar configuration. These cosmetic settings are easy to overlook but affect how the space looks to users.

Common Migration Pitfalls

Even with careful planning, things go wrong. Here are the five most common issues teams encounter during Confluence migrations and how to fix them.

Pitfall 1: Broken internal links

The problem: Pages in Confluence often link to each other using full URLs. When content moves to a new instance, those URLs point to the old server. Visitors see 404 errors instead of the linked page.

The fix: Before migrating, identify pages with absolute internal links. After migration, use Confluence's search to find and update broken links. If you are migrating within the same instance (space reorganization), relative links will survive the move. For cross-instance migrations, consider using the Confluence REST API to do a bulk find-and-replace of the old base URL with the new one.

Pitfall 2: Missing attachments

The problem: Attachments are frequently left behind during migrations because many export tools handle page content only. Teams discover the issue weeks later when someone opens a page and sees broken image icons.

The fix: Always export attachments separately. Confluence's built-in space export has an "Include attachments" checkbox — use it. If you are using Modern Importer Exporter for Confluence, supplement the content export with Confluence's native attachment export. Verify attachment counts match between source and target before considering the migration complete.

Pitfall 3: Macro rendering failures

The problem: Macros that depend on external data (Jira issues, database queries, third-party integrations) may render as blank placeholders or error messages after migration. This happens when the target instance does not have the same apps installed, or when macro configurations reference IDs that do not exist in the new environment.

The fix: Install all required marketplace apps on the target instance before importing content. For Jira macros, ensure the Jira integration is configured on the target instance. After migration, open each page that uses macros and verify they render correctly. Keep a list of pages with complex macros so you can check them systematically.

Pitfall 4: Permission and access control gaps

The problem: After migration, users report they cannot access pages they previously could. This happens because permissions are not preserved during most export/import operations. In some cases, the space defaults to "Public" access, exposing sensitive content.

The fix: Document all permission structures before migration using the audit spreadsheet from Step 1. Immediately after import, apply space-level restrictions first, then page-level restrictions. Consider temporarily restricting the entire migrated space to admins only, then opening access incrementally as you verify each section.

Pitfall 5: Large space timeouts

The problem: Attempting to export or import an entire space with thousands of pages in one operation causes browser timeouts, server errors, or incomplete exports. The operation appears to hang or fails silently.

The fix: Break large operations into batches. Modern Importer Exporter for Confluence recommends batches of 50 to 100 pages. Close other browser tabs to free memory. Use a wired internet connection for operations involving more than 1,000 pages. If using built-in XML export, try exporting specific page trees instead of the entire space.

Confluence Migration Checklist

Use this checklist to track your migration progress. Each item corresponds to a critical step in the process.

Pre-migration

• Inventory all spaces, page counts, and attachment counts
• Identify stale content for archival (pages not modified in 12+ months)
• Document all space-level and page-level permissions
• List macros and third-party app integrations in use
• Verify admin access on both source and target instances
• Notify users of planned migration window
• Create a backup of the target instance (in case you need to roll back)

Export

• Choose export tool based on migration scenario
• Test export with a small sample (5 to 10 pages)
• Verify the test export contains expected content and formatting
• Export content in batches if spaces are large
• Export attachments separately using Confluence's built-in tool
• Save all export files in a dated, organized folder structure
• Verify export file sizes match expected content volume

Import

• Install required marketplace apps on target instance
• Configure Jira integration on target instance (if using Jira macros)
• Test import with the small sample export
• Verify test import: page hierarchy, formatting, links
• Import content in batches
• Import attachments
• Record success/error counts for each batch

Post-migration validation

• Verify page hierarchy in every migrated space
• Spot-check internal links across 10+ representative pages
• Verify a sample of attachments download and open correctly
• Test macro rendering on pages that use complex macros
• Review tables, code blocks, and layouts for formatting issues
• Reapply space-level permissions from pre-migration documentation
• Reapply page-level restrictions
• Update space descriptions, logos, and sidebar configurations
• Redirect old URLs to new locations (if cross-instance migration)
• Communicate completion to users and provide links to migrated spaces

Choosing the Right Format for Your Migration

The export format you choose affects what survives the migration. Here is a quick guide:

Format	Best For	Fidelity	Re-importable
XML (Confluence built-in)	Full space migration between Confluence instances	High — preserves metadata, page history	Yes, via Confluence's restore function
ADF JSON	Content migration with Modern Importer Exporter	High — native Confluence document format	Yes, via Modern Importer Exporter import
ADF XML	Integration with XML-based systems	High — full structure preserved	Yes, via Modern Importer Exporter import
HTML	Web publishing, static site generation, offline viewing	Medium — complex layouts may be simplified	Yes, basic conversion back to Confluence format
Markdown	Developer wikis, GitHub/GitLab integration	Low to medium — limited formatting support	Import only (cannot be exported from Modern Importer Exporter)

For the highest fidelity migration between Confluence instances, use either Confluence's built-in XML export or ADF JSON export with Modern Importer Exporter. For migrations where the target is not Confluence (a static site, a different wiki, or an archive), HTML or Markdown are more appropriate.

Related Resources

• Modern Importer Exporter for Confluence Documentation — Complete user guide for the import/export app, including bulk operations and format details.
• Import Export for Confluence Compared — Side-by-side comparison of every Confluence import/export app on the Atlassian Marketplace, with feature breakdowns and honest pros and cons.
• Export Jira Issues to Excel/CSV — If your Confluence migration involves Jira-linked content, this guide covers exporting Jira issues for reference.

---

Have questions about your Confluence migration? Reach out at service@ngpilot.com — we help teams plan and execute content migrations every week.