Summary

This guide provides some workarounds if you need to rename a space in Confluence.

Confluence Cloud, Server, and Data Center do not provide a method for ~~copying a space or~~ changing the space key. The following feature requests have been raised.

T	Key	Summary	Status

Loading...

Refresh

Since the CONFSERVER-3191 - Getting issue details... STATUS is fixed with Confluence 8.3, we now have a built-in functionality for copying a space.

Limitations

Apart from the built-in method that is introduced with Confluence 8.3, the information on this page is provided for informational purposes only, and will not be directly supported by Atlassian, should you wish to pursue possible workarounds in light of this limitation.

This information is not actively maintained and should be thoroughly tested before applying it to any production environment.

Solution 1 - Use built-in 'Copy Space' functionality

Available for SERVER DATA CENTER

The best option is to use the built-in functionality that is introduced with Confluence 8.3. This functionality can help you copy a space:

Copy a Space

Note that this method does not copy the history of Pages and Blogposts. Please check the ' What will be copied from a space? ' section of the mentioned KB article.

Alternative - Use an app from the Atlassian Marketplace

Available for CLOUD SERVER DATA CENTER

Similar to the above, there are other options in our Atlassian Marketplace. Third-party apps can have some extended functionalities that may fulfill your business requirement better than the built-in. Examples:

Search for Copy Space apps on Marketplace
Command-line tools such as the Bob Swift CLI tool can also be useful for bulk actions like copying a space.

Solution 2 - Use the copy page hierarchy feature

Available for CLOUD SERVER DATA CENTER

The ability to copy a page and all its child pages was introduced in Confluence 6.0. This can be useful if you need to copy the contents of an entire space.

The following instructions are for the Confluence Server or Data Center, but you can follow a similar process in Cloud.

To copy a space using copy page hierarchy:

Create a new space and set any permissions, look and feel, and other customizations.
In your source space, go to Space Tools > Reorder pages, and temporarily move any pages that exist at the root of the space to be a child of the homepage. This is to ensure the connection between pages in links and macros are preserved when copying. If you have no pages at the root, you can skip this step.
On the space homepage, select … > Copy.
Specify your new space as the destination.
Select Include child pages.
Make sure all checkboxes are selected so that labels, attachments, and restrictions are all preserved.
Select Copy. This might take a little while, depending on how big your space is. Pages are copied in batches, so don’t worry if they’re not all there immediately.
Go back to the source space, and move any pages you temporarily moved, back to the root of the space.
In the new space, your copied pages will be a child of the new space’s existing homepage. Go to Space tools > Reorder pages, and move your copied pages to the root of the space, so they are not a child of the homepage.
Go to Space Tools > Overview and set your copied homepage as the space homepage.
Delete the unwanted homepage.
Move any other pages that should not be a child of the homepage (such as an included library) back to the root of the space.

Note that this feature will not preserve the page history, likes, or comments of the source pages.

See the whole process in this short video.

Note that incoming links from other spaces will continue to point to your source space.

Solution 3 - export the space and modify the XML

Available for CLOUD SERVER DATA CENTER

It is possible to manually clone or rename a space by modifying an XML backup of the target space.

Please be aware of following points while working with this Solution.

Make sure you have a backup of your site and use a staging environment to test your changes before attempting this in production.
This procedure can cause the issue described in the following bugs:
- CONFSERVER-78062 - Jira Link doesn't appear/show count after import space
- CONFSERVER-60357 - Confluence pages aren't referenced under "Mentioned in" in Jira after space restore
If you're changing the space key in order to import it into your Atlassian Confluence Cloud site, make sure you'll do it on a space-by-space basis. Atlassian Confluence Cloud does not support a full site import.

If you are renaming many spaces at once, it may be easier to export the full instance. Please note that in the case of a full site export, the exportDescriptor.properties file will not need to be altered, but you will need to change the space keys in:

<export_folder>/plugin-data/com.atlassian.activeobjects.confluence.spi/activeObjectsBackupRestoreProvider.pdata

We strongly recommend testing your import on a staging server first, as full site backups are known to be problematic when importing back into Confluence. If you encounter any issues you should use the space-by-space method.

Stage 1: Generate the XML backup and create a test instance

Select a new, unique space key and name for the second space. Space keys may only consist of ASCII letters or numbers (A-Z, a-z, 0-9) and no empty spaces, special characters or underscore are allowed in the key. If we have one of the invalid characters in the space key, the re-import will fail with a stack trace.
Clone your production Confluence instance to a test server on another computer now. (For instructions, see Restoring a Test Instance from Production.) You should now have a production server and test server both containing the same data and can avoid the risk of corrupting your production Confluence instance.
On the test server, log in as an administrator.
Go to Space > Space Tools > Content Tools > Export > XML > Next > Full Export > Export Space and export the target space as XMLincluding attachments.
Save the space backup.

Stage 2: Edit the entities.xml file (via Bash & PowerShell scripts OR manually)

Scripts

If using the Bash script, then skip Stage 3: Edit the exportDescriptor.properties file step.

If using the PowerShell script, then execute Stage 3: Edit the exportDescriptor.properties file step.

If using any of the two scripts, then skip the Stage 6: Rename Space References step.

Bash

# variables (all uppercase except for 'old_space_key' and 'old_space_name', Supply them as they are; there's no need to change them to uppercase or lowercase—keep them as they are.)
zipfile="<path/myfile.zip>"
oldkey_uppercase="<OLD SPACE KEY>"
oldname_uppercase="<OLD SPACE NAME>"
newkey_uppercase="<NEW SPACE KEY>"
newname_uppercase="<NEW SPACE NAME>"
old_space_key="<Actual Space Key>"
old_space_name="<Actual Old Space Name>"
# from here on, no changes are needed
# the variables defined above will be used below

# the lower case variables will be defined here based on the above, and you do not need to change them
oldkey_lowercase=$(echo "${oldkey_uppercase}" | tr [:upper:] [:lower:])
oldname_lowercase=$(echo "${oldname_uppercase}" | tr [:upper:] [:lower:])
newkey_lowercase=$(echo "${newkey_uppercase}" | tr [:upper:] [:lower:])
newname_lowercase=$(echo "${newname_uppercase}" | tr [:upper:] [:lower:])

# unzipping the all the file like entities.xml,exportDescriptor.properties and attachments
unzip ${zipfile};

# commands to actually edit the entities.xml and exportDescriptor.properties files
sed -i "s/\[CDATA\[${oldname_uppercase}\]/\[CDATA\[${newname_uppercase}\]/g" entities.xml; 
sed -i "s/\[CDATA\[${old_space_name}\]/\[CDATA\[${newname_lowercase}\]/g" entities.xml; 
sed -i "s/\[CDATA\[${oldname_lowercase}\]/\[CDATA\[${newname_lowercase}\]/g" entities.xml;
sed -i "s/\[CDATA\[${oldkey_uppercase}\]/\[CDATA\[${newkey_uppercase}\]/g" entities.xml;
sed -i "s/\[CDATA\[${old_space_key}\]/\[CDATA\[${newkey_lowercase}\]/g" entities.xml;
sed -i "s/\[CDATA\[${oldkey_lowercase}\]/\[CDATA\[${newkey_lowercase}\]/g" entities.xml;

sed -i "s/spaceKey:${oldkey_uppercase}/spaceKey:${newkey_uppercase}/g" entities.xml;
sed -i "s/spaceKey:${old_space_key}/spaceKey:${newkey_lowercase}/g" entities.xml;

# For latest Version of Confluence 
sed -i "s|<property name=\"key\">${oldkey_uppercase}|<property name=\"key\">${newkey_uppercase}|g" entities.xml
sed -i "s|<property name=\"key\">${oldkey_lowercase}|<property name=\"key\">${newkey_uppercase}|g" entities.xml;
sed -i "s|<property name=\"key\">${old_space_key}|<property name=\"key\">${newkey_uppercase}|g" entities.xml;
sed -i "s|<property name=\"lowerKey\">${oldkey_lowercase}|<property name=\"lowerKey\">${newkey_lowercase}|g" entities.xml;
sed -i "s|<property name=\"lowerKey\">${oldkey_uppercase}|<property name=\"lowerKey\">${newkey_lowercase}|g" entities.xml;
sed -i "s|<property name=\"lowerKey\">${old_space_key}|<property name=\"lowerKey\">${newkey_lowercase}|g" entities.xml;
sed -i "s|<property name=\"name\">${oldname_uppercase}|<property name=\"name\">${newname_uppercase}|g" entities.xml;
sed -i "s|<property name=\"name\">${oldname_lowercase}|<property name=\"name\">${newname_uppercase}|g" entities.xml;
sed -i "s|<property name=\"name\">${old_space_name}|<property name=\"name\">${old_space_name}|g" entities.xml;

sed -i "s|<spaceKey>${oldkey_uppercase}|<spaceKey>${newkey_uppercase}|g" entities.xml;

sed -i "s|<property name=\"context\">${oldkey_uppercase}|<property name=\"context\">${newkey_uppercase}|g" entities.xml;


sed -i "s/spaces\/${oldkey_uppercase}/spaces\/${newkey_uppercase}/g" entities.xml;
sed -i "s/spaces\/${old_space_key}/spaces\/${newkey_lowercase}/g" entities.xml;


sed -i "s/spaceKey=${oldkey_uppercase}/spaceKey=${newkey_uppercase}/g" exportDescriptor.properties;
sed -i "s/spaceKey=${old_space_key}/spaceKey=${newkey_lowercase}/g" exportDescriptor.properties;

sed -i "s/spaceKeys=${oldkey_uppercase}/spaceKey=${newkey_uppercase}/g" exportDescriptor.properties;
sed -i "s/spaceKeys=${old_space_key}/spaceKey=${newkey_lowercase}/g" exportDescriptor.properties;

sed -i "s/spacekey=${oldkey_uppercase}/spacekey=${newkey_uppercase}/g" entities.xml;
sed -i "s/spacekey=${old_space_key}/spacekey=${newkey_lowercase}/g" entities.xml;

sed -i "s/ri:space-key=\"${oldkey_uppercase}\"/ri:space-key=\"${newkey_uppercase}\"/g" entities.xml;
sed -i "s/ri:space-key=\"${old_space_key}\"/ri:space-key=\"${newkey_lowercase}\"/g" entities.xml;

sed -i "s/ri:space-key=${oldkey_uppercase}/ri:space-key=${newkey_uppercase}/g" entities.xml;
sed -i "s/ri:space-key=${old_space_key}/ri:space-key=${newkey_lowercase}/g" entities.xml;

sed -i "s/<ac:parameter ac:name=\"spaces\">${oldkey_uppercase}<\/ac:parameter>/<ac:parameter ac:name=\"spaces\">${newkey_uppercase}<\/ac:parameter>/g" entities.xml;
sed -i "s/<ac:parameter ac:name=\"spaces\">${old_space_key}<\/ac:parameter>/<ac:parameter ac:name=\"spaces\">${newkey_lowercase}<\/ac:parameter>/g" entities.xml;

sed -i "s/<ac:parameter ac:name=\"spaceKey\">${oldkey_uppercase}<\/ac:parameter>/<ac:parameter ac:name=\"spaceKey\">${newkey_uppercase}<\/ac:parameter>/g" entities.xml;
sed -i "s/<ac:parameter ac:name=\"spaceKey\">${old_space_key}<\/ac:parameter>/<ac:parameter ac:name=\"spaceKey\">${newkey_lowercase}<\/ac:parameter>/g" entities.xml;


sed -i "s/\"parentPageSpaceKey\":\"${oldkey_uppercase}\"/\"parentPageSpaceKey\":\"${newkey_uppercase}\"/g" entities.xml;
sed -i "s/\"parentPageSpaceKey\":\"${old_space_key}\"/\"parentPageSpaceKey\":\"${newkey_lowercase}\"/g" entities.xml;

sed -i "s/spacekey=${oldkey_lowercase}/spacekey=${newkey_lowercase}/g" entities.xml;
sed -i "s/spacekey=${old_space_key}/spacekey=${newkey_lowercase}/g" entities.xml;

sed -i "s/spacekey=${oldkey_lowercase}/spacekey=${newkey_lowercase}/g" entities.xml;
sed -i "s/spacekey=${old_space_key}/spacekey=${newkey_lowercase}/g" entities.xml;

# zipping the updated entities.xml and exportDescriptor.properties files back into the zip file
zip -ur ${zipfile} entities.xml exportDescriptor.properties attachments;

When implementing the above step, OS X users might encounter the following issue: Error when using 'sed' with 'find' command on OS X: "invalid command code ." See linked community discussion for possible solutions.

PowerShell

$inputOldKeyL = "oldname"
$inputNewKeyL = "newname"
$exportFolder = "path_to_export_folder"

$oldKeyL = $inputOldKeyL.ToLower()
$newKeyL = $inputNewKeyL.ToLower()
$oldKeyU = $oldKeyL.ToUpper()
$newKeyU = $newKeyL.ToUpper()

$fileIn = Join-Path $exportFolder "entities.xml"
$fileOut = Join-Path $exportFolder "entities2.xml"

$fileContent = [System.IO.File]::ReadAllText($fileIn)
$afterReplace = $fileContent.
Replace("<property name=`"lowerDestinationSpaceKey`"><![CDATA[$oldKeyL]]></property>", "<property name=`"lowerDestinationSpaceKey`"><![CDATA[$newKeyL]]></property>").
Replace("<property name=`"lowerKey`">![CDATA[$oldKeyL]]></property>", "<property name=`"lowerKey`">![CDATA[$newKeyL]]></property>").
Replace("[$oldKeyU]", "[$newKeyU]").
Replace("[$oldKeyL]", "[$newKeyL]").
Replace("spaceKey=$oldKeyU", "spaceKey=$newKeyU").
Replace("spaceKey=$oldKeyL", "spaceKey=$newKeyL").
Replace("[$oldKeyU`:", "[$newKeyU`:").
Replace("key=$oldKeyU]", "key=$newKeyU]").
Replace("<spaceKey>$oldKeyU</spaceKey>", "<spaceKey>$newKeyU</spaceKey> ").
Replace("ri:space-key=`"$oldKeyU`"", "ri:space-key=`"$newKeyU`"").
Replace("ri:space-key=$oldKeyU", " ri:space-key=$newKeyU").
Replace("<ac:parameter ac:name=`"spaces`">$oldKeyU</ac:parameter>", "<ac:parameter ac:name=`"spaces`">$newKeyU</ac:parameter>").
Replace("<ac:parameter ac:name=`"spaceKey`">$oldKeyU</ac:parameter>", "<ac:parameter ac:name=`"spaceKey`">$newKeyU</ac:parameter>")
[System.IO.File]::WriteAllText($fileOut, $afterReplace)
Rename-Item -Path $fileIn -NewName "entities_old.xml"
Rename-Item -Path $fileOut -NewName "entities.xml"

Manual

Open the space backup file with a zip file editor and find the file entities.xml.
Edit entities.xml in a text editor.
Do a 'Search & Replace' on the old space name as shown below. Swap out Old Space Name and New Space Name for the actual names.

Search for
Replace with
[CDATA[Old Space Name]
[CDATA[New Space Name]
Do a 'Search' for any occurrences of the old space name that occur in user content. You may wish to replace some or all of these references with the new space name. Replace Old Space Name and New Space Name with the actual names.

Search For
Old Space Name

Do 'Search & Replaces' for each of the space key patterns as shown below.

Note carefully that letter casing matters here: the placeholder variables OLDKEY/NEWKEY represent keys in UPPER or MIXED-CASE and oldkey/newkey represent keys in all-lowercase.

Search For	Replace With
`OLDKEY`	`NEWKEY`
`spaceKey=OLDKEY`	`spaceKey=NEWKEY`
`[OLDKEY:`	`[NEWKEY:`
`key=OLDKEY]`	`key=NEWKEY]`
`<spaceKey>OLDKEY</spaceKey>`	`<spaceKey>NEWKEY</spaceKey>`
`ri:space-key="OLDKEY"`	`ri:space-key="NEWKEY"` Perform this step if links within the renamed space should point to themselves and not the original space key, otherwise, skip
`ri:space-key=OLDKEY`	`ri:space-key=NEWKEY` Perform this step if links within the renamed space should point to themselves and not the original space key, otherwise, skip
`<ac:parameter ac:name="spaces">OLDKEY</ac:parameter>`	`<ac:parameter ac:name="spaces">NEWKEY</ac:parameter>`
`<ac:parameter ac:name="spaceKey">OLDKEY</ac:parameter>`	`<ac:parameter ac:name="spaceKey">NEWKEY</ac:parameter>`
`<property name="lowerDestinationSpaceKey"><![CDATA[NEWKEY]]></property>`	`<property name="lowerDestinationSpaceKey"><![CDATA[newkey]]></property>` Beware new key is used on both sides
`<property name="lowerKey"><![CDATA[NEWKEY]]></property>`	`<property name="lowerKey"><![CDATA[newkey]]></property>` Beware new key is used on both sides
`<property name= "lowerKey"><![CDATA[oldkey]]></property>`	`<property name= "lowerKey"><![CDATA[newkey]]></property>`
`spaceKey=OLDKEY`	`spaceKey=NEWKEY`
`spacekey=oldkey`	`spacekey=newkey`

Save the modified entities.xml.
Overwrite the original entities.xml in the space back up with the modified version.

Stage 3: Edit the exportDescriptor.properties file

Also, edit the exportDescriptor.properties file in a text editor
Change the spaceKey value in the exportDescriptor.properties file to the new spaceKey

Stage 4: Restore to a lower (Test/Dev/Staging) environment for verification

Login to your test instance as a Confluence administrator.
Go to Administration menu > General Configuration > Backup & Restore. Under 'Upload a zipped backup to Confluence', browse to select the modified space backup. Check the 'Build index' option and select 'Upload & Restore'.
Once the restore process has been completed, access the new space and test that you can access pages, embedded links, and attachments. Any error in this step indicates that your search and replace was performed incorrectly and you should retry from step 2.

Stage 5: Import the space into Prod

Back up your production instance now.
Login to the production instance as a Confluence administrator.
Go to Administration menu > General Configuration > Backup & Restore. Under 'Upload a zipped backup to Confluence', browse to select the modified space backup. Check the 'Build index' option and select 'Upload & Restore' If any data loss occurs as a result of using this workaround, immediately revert to the backup.
Once the restore process has been completed, access the new space and test that you can access pages, embedded links, and attachments. If any error occurs during this step, revert to the site backup.
If renaming a space, you can delete the old space by going to Space > Space Tools > Overview > Delete Space. Click OK to remove the old space.

Stage 6: Rename Space References

Links in other spaces to the old space will remain unchanged. If you are renaming a space, you will need to change these links to point to the new space. Users who are copying a space can leave the links pointing to the original space by skipping this stage.

Changing these links depends on if you want to change every link or only some. If not all links must be changed or you are unwilling to stop your production instance, this must be done by editing each page individually. If all links must be changed, follow the instructions below.

Create a site XML backup including attachments from Administration menu > General Configuration > Backup & Restore.
Save the site XML backup file.
Stop the production instance.
Create two copies of the site backup. Keep one copy as the original, unmodified backup, the other will be modified. Rename the backups so that it is clear which is being modified.
Open the copy for modification and edit entities.xml.
Do four 'Search & Replaces' on each of the references to the old space key as shown below. Swap out oldkey and newkey for the actual keys

Search for
Replace with
[oldkey]
[newkey]
spaceKey=oldkey
spaceKey=newkey
[oldkey:
[newkey:
key=oldkey]
key=newkey]
Save the updated entities.xml back into the modified site XML backup file
Start the production instance
Import the modified site XML backup from Administration menu > General Configuration > Backup & Restore. If you have any problems, revert to the original unmodified back up and redo the links manually instead

Confluence Support

Get started

Knowledge base

Products

Jira Software

Jira Service Management

Jira Work Management

Confluence

Bitbucket

Resources

Documentation

Community

System Status

Suggestions and bugs

Marketplace

Billing and licensing

How to copy or rename a space in Confluence

Still need help?

Summary

Limitations

Solution 1 - Use built-in 'Copy Space' functionality

Available for SERVER DATA CENTER

Alternative - Use an app from the Atlassian Marketplace

Available for CLOUD SERVER DATA CENTER

Solution 2 - Use the copy page hierarchy feature

Available for CLOUD SERVER DATA CENTER

Solution 3 - export the space and modify the XML

Available for CLOUD SERVER DATA CENTER

Stage 1: Generate the XML backup and create a test instance

Stage 2: Edit the entities.xml file (via Bash & PowerShell scripts OR manually)

Scripts

Manual

Stage 3: Edit the exportDescriptor.properties file

Stage 4: Restore to a lower (Test/Dev/Staging) environment for verification

Stage 5: Import the space into Prod

Stage 6: Rename Space References

Search for	Replace with
`[oldkey]`	`[newkey]`
`spaceKey=oldkey`	`spaceKey=newkey`
`[oldkey:`	`[newkey:`
`key=oldkey]`	`key=newkey]`

Page

Viewport

Confluence

How to copy or rename a space in Confluence

Related content

Still need help?

Summary

Limitations

Solution 1 - Use built-in 'Copy Space' functionality

Available for SERVER DATA CENTER

Alternative - Use an app from the Atlassian Marketplace

Available for CLOUD SERVER DATA CENTER

Solution 2 - Use the copy page hierarchy feature

Available for CLOUD SERVER DATA CENTER

Solution 3 - export the space and modify the XML

Available for CLOUD SERVER DATA CENTER

Stage 1: Generate the XML backup and create a test instance

Stage 2: Edit the entities.xml file (via Bash & PowerShell scripts OR manually)

Scripts

Manual

Stage 3: Edit the exportDescriptor.properties file

Stage 4: Restore to a lower (Test/Dev/Staging) environment for verification

Stage 5: Import the space into Prod

Stage 6: Rename Space References

Related content