Skip to end of metadata
Go to start of metadata


JIRA running on Mac OS X should only be used for evaluation purposes!

Mac OS X is not a supported operating system for the JIRA server because until recently no supported Oracle JDK and JRE (formerly Sun JDK and JRE) was available for this operating system. It is our view that the cost of supporting JIRA on OS X would be better spent fixing bugs and developing other requested features.

Please note:

  • If you encounter problems with your JIRA server running on Mac OS X, they may not be fixed as we do not test JIRA with unsupported Java platforms.
  • However, JIRA users can still access your JIRA server through a supported browser on Mac OS X.

To install JIRA on Mac OS X, follow these steps:

Before you begin

Please ensure that you have set JAVA_HOME. (You don't need to install Java as it comes with Mac OS X.)

1. Download and Install JIRA

  1. Download the JIRA tar.gz file here.
  2. Unzip the downloaded file.

2. Set JIRA Home

You can specify any location on a disk for your JIRA home directory. Please be sure to specify an absolute path.

Please note that you cannot use the same JIRA home directory for multiple instances of JIRA. We recommend locating your JIRA Home Directory completely independently of the JIRA Installation Directory (i.e. not nesting one within the other) as this will minimize information being lost during major operations (e.g. backing up and restoring instances).

To specify the location of your JIRA Home Directory:

  1. Use the JIRA Installation Directory page to locate the file and open.
  2. Set the value of the 'jira.home' property to the desired location for your JIRA Home Directory.
  3. Use the JIRA Configuration Tool (included with all JIRA distributions except JIRA WAR) to change the location of your JIRA Home Directory.
  4. Set an environment variable named JIRA_HOME in your operating system whose value is the location of your JIRA Home Directory. To do this, do one of the following:
    1. Enter the following command at a shell/console prompt before running JIRA:
      1. export JIRA_HOME=/path/to/jira/home
    2. Specify the command above in a script used to start JIRA.

3. Create a Dedicated User Account on the Operating System to Run JIRA

A dedicated user should be created to run JIRA, as JIRA runs as the user it is invoked under and therefore can potentially be abused. For example:
  • If your operating system is *nix-based (for example, Linux or Solaris), type the following in a console:
    $ sudo /usr/sbin/useradd --create-home --comment "Account for running JIRA" --shell /bin/bash jira
  • If your operating system is Windows:
    1. Create the dedicated user account by either:
      • Typing the following at the Windows command line:
        > net user jira mypassword /add /comment:"Account for running JIRA"
        (This creates a user account with user name 'jira' and password 'mypassword'. You should choose your own password.)
      • Opening the Windows 'Computer Management' console to add your 'jira' user with its own password.
    2. (Optional) Use the Windows 'Computer Management' console to remove the 'jira' user's membership of all unnecessary Windows groups, such as the default 'Users' group.
      (tick) If Windows is operating under a Microsoft Active Directory, ask your Active Directory administrator to create your 'jira' account (with no prior privileges).

Ensure that only the following directories can be written to by this dedicated user account (e.g. 'jira'):

(warning) Do not make the JIRA Installation Directory itself writeable by the dedicated user account.

(info) See also Tomcat security best practices.

4. Start JIRA

Run bin/ to start JIRA.

JIRA will be launched in a black 'Tomcat' window (do not close this window). Wait until the startup messages have finished.

To access JIRA, go to your web browser and type this address: http://localhost:8080.

If JIRA does not appear, you may need to change the port that JIRA runs on.

If something goes wrong, please verify that Java is installed correctly. If the problem persists, please contact us — we're happy to help.

5. Run the Setup Wizard

See Running the Setup Wizard.

Next Steps

  • See JIRA 101 to start creating Projects, creating Users, and customizing your JIRA instance.
  • By default, JIRA uses the standard Tomcat port (i.e. 8080). If you need another application to run on that port, either now or in the future, please see Changing JIRA's TCP Ports.
  • As part of its installation process, JIRA automatically installs, configures and connects itself to an HSQLDB database. This is fine for evaluation purposes, however HSQLDB is prone to data corruption. For production installations, we strongly recommend that you connect JIRA to an external database.
  • To get the most out of JIRA, please see Optimizing Performance.