Restoring a Space

You can export a space – including pages, comments and attachments – to a zip that contains an XML file and, optionally, all the attachments in the space. To import the space to another Confluence site, restore the zip as described below.

You need System Administrator permissions in order to restore a space from an XML zip file.

Export and import compatibility

To find out which versions your current Confluence version can accept space exports from, go to  > General Configuration  > Backup and Restore.

If you need to import a space from Confluence 5.3 or earlier, you'll need to follow a workaround

To find out what is included in an XML export, see Export Content to Word, PDF, HTML and XML.

You can't import into an earlier version of Confluence.

For example, if you export a space from Confluence 5.9, you can't import it into Confluence 5.5. 

If your export is from Confluence Cloud, you can only import it into Confluence 6.0 or later.

On this page:

Related pages:

Importing a space from Confluence Cloud

As the way users are managed is different in Confluence Cloud there are a few more considerations when importing a space from Confluence Cloud into Confluence Server or Data Center.

See Import a space from Confluence Cloud for a step-by-step guide.

Importing a space from Confluence Server or Data Center

(warning) We recommend performing a full backup of your database before importing a space. Occasionally the space import process may fail, and a backup will make it easier for you to roll back. 

There are two ways to import a space – by uploading a file, or from a directory on your Confluence server. Uploading a file is only suitable for small spaces. For best results, we recommend importing from the restore directory.  

Upload a site or space export file

To upload and import a small space:

  1. Go to  > General Configuration > Backup and Restore
  2. Under Upload a site or space export file, click Choose File and browse for your space export file.
  3. Uncheck Build Index if you want to create the index at a later stage.
  4. Choose Upload and import

Once the import is complete, you can either navigate directly to the space, or head to the Space Directory

Import from the home directory

Importing from the home directory is a great alternative for large spaces, as you don't need to upload the file via your browser. 

To import a space from the home directory: 

  1. Copy your space export file to <confluence-home>/restore. 
    (If you're not sure where this directory is located, the path is listed in the Backup and Restore screen)
  2. Go to  > General Configuration > Backup and Restore.
  3. Select your space export file under Import from the Home Directory.
  4. Uncheck Build Index if you want to create the index at a later stage.
  5. Choose Import.

Building the index is optional during the import process. The content of your imported space won't be searchable until the index is created, but, if you have a very large site, rebuilding the index can take a long time and impact your site's performance. Alternatively, you can rebuild the index manually at a low peak time.

Groups and permissions

Importing a space will not import any users or groups that may have been granted specific space permissions in your source Confluence site. This means that if any pages are restricted to these groups, you may not be able to see them until you recreate these groups in your destination site.

Check the size of a space before importing

It's important to check the size of your exported space before you attempt it import it as it may mean you need to use a particular method, or complete the import at a quieter time. 

The total file size of the zip will determine whether you can upload the file through the browser, or if you need to use the home directory method. 

The size of the entities.xml file provides an indication of the amount of entities such as pages, versions, and comments. A very large time may take quite some time to import. 

To check the size of the entities.xml  in an exported space:

  1. Unzip the space export file.
  2. Navigate to the entities.xml  file and check the sizeof that file. The way you do this will depend on your operating system. 

Troubleshooting

If you have problems importing a space, check out these hints. 

  • Is your file too large to upload? 
    This is a very common problem. It happens when the file can't be uploaded to the server in time. To avoid this problem, drop your export file into the <confluence-home>/restore directory and import it from there. 
  • Are you trying to import into an earlier version of Confluence?  
    This is not possible. You can only import a space into the same version or a later compatible version. 
  • Is your space export file from Confluence Cloud? 
    You can only import this file into Confluence 6.0 or later. Trying to import into earlier versions can cause major problems. See Import a space from Confluence Cloud for other considerations.
  • Does a space with the same space key already exist? 
    Space keys are unique, so if you already have a space with the same key, you'll need to delete the existing space before importing the new one.
  • Is the import timing-out or causing out of memory errors? 
    If the space to be imported is very large, you may need to temporarily increase the memory available to Confluence. See How to fix out of memory errors by increasing available memory.
  • Did you download the export file on a Mac?
    If you get an error saying that Confluence can't find the  exportDescriptor.properties  file, chances are OS X has unzipped the backup for you and sent the original zipped file to the trash. You need to retrieve the original zip file from the trash and then try the import again.
  • Did your import fail?  Sometimes importing a space may fail because the process times out or runs out of memory. This can lead to data being left behind in your database. See After a failed space import, it's not possible to re-import because of leftover space data for more information. 
  • Do you have adequate disk space? 
    Confluence will need to make copies of the file being imported at various points during the import process. Make sure you have enough disk space to temporarily accomodate multiple copies of the site export file. 

Workaround for restoring spaces from Confluence 5.3 and earlier

If you need to import a space from a version prior to Confluence 5.3 into a later version of Confluence, you can use a temporary Confluence installation to upgrade the space export to the right version number:

  1. Download the same version of Confluence as the version you exported the space from (you can get older versions of Confluence at the Confluence Downloads Archive).
  2. Install that version of Confluence on a temporary server.
  3. Import the space into this temporary Confluence site.
  4. Upgrade Confluence on your temporary site to the same version as the site where you want to import the space (see Upgrading Confluence for instructions).
  5. Export the space from your temporary Confluence site (it'll now have the right version number).
  6. Import the space into your production Confluence site.
Last modified on Jan 25, 2022

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.