How to backup and restore your Atlassian Bitbucket instance

By | October 1, 2016

There are 3 options for you to backup your Atlassian Bitbucket instance.

  • Bitbucket Server Backup Client for v4.7 or lower
  • Bitbucket Zero Downtime Backup for v4.8 or higher
  • Copy and paste of your home directory

Bitbucket Server Backup Client

If you are running Bitbucket version 4.7 or lower, you will need to download an application called “Bitbucket Server Backup Client”. Unlike JIRA or Confluence, there is no easy backup or restore option in the admin menu.

The process is straight forward though. You can download the application and see the documentations here.

Note that you cannot use the UPM to try and download Bitbucket Server Backup Client. If you try, you will get this message:


Once you have downloaded it manually, install Bitbucket Server Backup Client and then either create a properties file for Bitbucket Server Backup Client to read from or just enter them in manually in the command line. Here is an example where the parameters and provided directly in the command line:

>> java -Dbitbucket.password="admin" -Dbitbucket.user="admin" -Dbitbucket.baseUrl="http://localhost:7990" -Dbitbucket.home=/Users/cloudnthings/Atlassian/bitbucket46 -Dbackup.home=/Users/cloudnthings/bitbucketbackup -jar bitbucket-backup-client.jar

This is what you should see:


You should then see the backup file you created.


To restore the data, follow the documentation and run the following:

>> java -Dbitbucket.home="path/to/bitbucket/home" -jar bitbucket-restore-client.jar /path/to/original/backup/file

Bitbucket Zero Downtime Backup

If you have v4.8 or newer, you can use the new feature called Bitbucket Zero Downtime Backup. Note however that this new feature requires you to download a script file from git and configure the script with your database details and with your instance parameters. So it’s similar to Bitbucket Server Backup Client with the properties file.

Copy and paste of your home directory

Of course the last option is to do a copy and paste of your Bitbucket home directory.


To restore an instance using Bitbucket Server Backup Client, download a new version of Bitbucket and extract it. (I’m using the .tar version). You don’t want to start it up yet because this will go through the set up and you’ll end up with a proper home directory. ie a non empty home directory and this is the error you’ll encounter:

>> bitbucket-20161001-125421-374.tar could not be restored com.atlassian.bitbucket.internal.backup.client.RestoreException: The configured BITBUCKET_HOME /Users/cloudnthings/Atlassian/bitbucket481 is not empty. It contains:

Run the command shown in the docs.

>> ja    va -Dbitbucket.home="path/to/bitbucket/home" -jar bitbucket-restore-client.jar /path/to/original/backup/file

And this should be the result:

screen-shot-2016-10-01-at-2-16-19-pm screen-shot-2016-10-01-at-2-17-39-pm

This process was verified by backing up v4.6 and restoring to v4.8.1

Leave a Reply

Your email address will not be published. Required fields are marked *