Install Bitbucket Server on Windows from a zip file
This page describes how to install Bitbucket Server in a production environment, with an external database, manually using a zip file.
This method gives you the most control of the installation process.
Other ways to install Bitbucket Server:
On this page
Before you begin
Before you install Bitbucket Server, there are a few questions you need to answer.
Are you using a supported operating system and Java version?
Check the Supported Platforms page for the version of Bitbucket Server you are installing. This will give you info on supported operating systems, databases and browsers.
Good to know:
- We don't support installing Bitbucket Server on macOS for production sites.
- The Bitbucket Server installer includes Java (JRE) and Tomcat, so you don't need to install these separately.
Do you want to run Bitbucket Server as a service?
Running Bitbucket Server as a service means that Bitbucket Server will automatically startup when Windows is started.
You should use the Windows installer if you want to run Bitbucket Server as a service.
If you choose not to run Bitbucket Server as a service:
- You will start and stop Bitbucket Server by running the
start-bitbucket.batfile in your Bitbucket Server installation directory.
- Bitbucket Server will be run as the user account that was used to install Bitbucket Server, or you can choose to run as a dedicated user.
- Bitbucket Server will need to be restarted manually if your server is restarted.
For more information about these options, see the pages:
Are ports 7990, 7992, and 7993 available?
Ports 7992 and 7993: Bitbucket Server's bundled Elasticsearch instance, which is required for search functionality, requires ports 7992 and 7993 be available. This is not configurable, so ensure these ports are available.
Is your database set up and ready to use?
Good to know:
Do you have a Bitbucket Server license?
Good to know:
- If you don't have a license you can create an evaluation license during setup, and be sure to use your business email address.
- If you already have a license key you'll be prompted to log in to my.atlassian.com to retrieve it, or you can enter the key manually during setup.
- If you're migrating from Bitbucket Cloud (bitbucket.org), you'll need a new license.
Do you have Git and Perl installed and on the right version?
Do not upgrade Git to the latest version until you check the Supported Platforms page for which version of Git is currently supported.
Check that you have all the other system requirements, including Perl, to avoid any trouble.
Is your JAVA_HOME variable set correctly?
Before you install Bitbucket Server, check that you're running a supported Java version and that the
JAVA_HOME environment variable is set correctly.
To check the JAVA_HOME variable:
Open a command prompt and type
echo %JAVA_HOME% and hit Enter.
- If you see a path to your Java installation directory, the
JAVA_Homeenvironment variable has been set correctly.
- If nothing is displayed, or only
%JAVA_HOME%is returned, you'll need to set the
JAVA_HOMEenvironment variable manually. See Setting the JAVA_HOME Variable in Windows for a step by step guide.
Install Bitbucket Server
1. Download Bitbucket Server
Download the zip file - www.atlassian.com/software/bitbucket/download.
2. Create the installation directory
Create your installation directory (with full control permission) – this is where Bitbucket will be installed. Avoid using spaces or special characters in the path. We'll refer to this directory as your
Extract the zip file to your
3. Create the home directory
Create your home directory (with full control permission) – this is where your Bitbucket Server data is stored. This should be separate to your installation directory. We'll refer to this directory as your
<home-directory>.A few things to note about setting up the home directory on Windows that will make life easier...
Keep the path length to the Bitbucket home directory as short as possible. See Bitbucket Server is unable to create the merge diff for pull requests for an explanation.
Don't use spaces in the path to the Bitbucket home directory.
set-bitbucket-home.batfile – uncomment the
BITBUCKET_HOMEline and add the absolute path to your home directory.Here's an example of what that could look like when you're done...
Tell Bitbucket Server where you created it by setting a
- Go to System Environment Variables in Windows.
- Click Environment Variables, and then New under 'System variables'.
- Enter "
BITBUCKET_HOME" as the Variable name, and the absolute path to your Bitbucket home directory as the Variable value. Don't use a trailing backslash.
4. Start Bitbucket
Change directory to the
<installation-directory>and run this command:
bin\start-bitbucket.batIf you're using a remote Elasticsearch instance...
Start Bitbucket Server by running
In your browser, go to
and run through the Setup Wizard.
Set up Bitbucket
The Setup Wizard runs automatically when you visit Bitbucket Server in your browser the first time it's started.
5. Connect to your database
- If you've not already done so, it's time to create your database. See the 'Before you begin' section of this page for details.
Select External as your database, then choose a Database Type from the dropdown menu and enter the details of your database.If you plan to use MySQL, there's an extra step...
The JDBC drivers for MySQL / MariaDB are not bundled with Bitbucket Server (due to licensing restrictions), so you need download and install the driver.
- Download the MySQL Connector/J JDBC driver from the download site.
- Expand the downloaded
- Copy the
.jarfile from the extracted directory to your
<Bitbucket home directory>/libdirectory.
6. Add your license key
You can also set the base URL at this step, (you can elect to do this later).
7. Create your administrator account
- Enter details for the administrator account.
Click either Go to Bitbucket - to go straight to the Bitbucket Server interface, or Integrate with JIRA - to create your connection with an existing JIRA application.
8. Start using Bitbucket Server
When setting up Bitbucket Server in a production environment, we recommend that you configure these aspects next:
- Connect Bitbucket Server to a user directory - manage users/groups stored in an external directory.
- Run Bitbucket Server as a dedicated user - run Bitbucket Server from a user account with restricted privileges.
- Secure the Bitbucket home directory - secure the home directory against unauthorized access.
- Proxy and secure Bitbucket Server - run Bitbucket Server behind a reverse proxy and enable HTTPS access.
- Establish a data recovery plan - backup the home directory and database of your instance.
Read more about setting up Bitbucket Server for an enterprise here: Using Bitbucket Server in the enterprise.