Ghidra Installation Guide

The installation information provided is effective as of Ghidra 11.2 and is subject to change with future releases.

• Platforms Supported
• Minimum Requirements
• Installing Ghidra
• Installation Notes
• Java Notes
• Ghidra Installation Directory Layout
• Building Native Components
• Installing the Debuggers' Python Dependencies
• Running Ghidra
• GUI Mode
• Ghidra Server
• Headless (Batch) Mode
• Single Jar Mode
• Extensions
• Ghidra Extension Notes
• Ghidra Development
• Upgrade Instructions
• General Upgrade Instructions
• Server Upgrade Instructions
• Troubleshooting & Help
• Launching Ghidra
• Using Ghidra
• Known Issues
• All Platforms
• Windows
• Linux
• macOS (OS X)

Platforms Supported

• Windows 10 or later (64-bit)
• Linux (64-bit)
• macOS 10.13 or later

NOTE: All 32-bit OS installations are now deprecated. Please contact the Ghidra team if you have a specific need.

Minimum Requirements

Hardware

• 4 GB RAM
• 1 GB storage (for installed Ghidra binaries)
• Dual monitors strongly suggested

Software

• Java 21 64-bit Runtime and Development Kit (JDK) (see Java Notes)
• Free long term support (LTS) versions of JDK 21 are provided by:
• Adoptium Temurin
• Amazon Corretto
• Python3 (3.9 to 3.12; for Debugger support)
• This is available from Python.org or most operating system's app stores or software repositories. For Linux it is recommended that the system's package repository be used to install a suitable version of Python.

(Back to Top)

Installing Ghidra

To install Ghidra, simply extract the Ghidra distribution file to the desired filesystem destination using any unzip program (built-in OS utilities, 7-Zip, WinZip, WinRAR, etc)

Installation Notes

• Ghidra does not use a traditional installer program. Instead, the Ghidra distribution file is simply extracted in-place on the filesystem. This approach has advantages and disadvantages. On the up side, administrative privilege is not required to install Ghidra for personal use. Also, because installing Ghidra does not update any OS configurations such as the registry on Windows, removing Ghidra is as simple as deleting the Ghidra installation directory. On the down side, Ghidra will not automatically create a shortcut on the desktop or appear in application start menus.
• When launching Ghidra for the first time on macOS, the macOS Gatekeeper feature may attempt to quarantine the pre-built unsigned Ghidra native components. Two techniques can be used to prevent this from happening:
  • Prior to extracting the Ghidra distribution file, running xattr -d com.apple.quarantine ghidra_<version>_<date>.zip from a terminal.
  • Prior to first launch, following the instructions in the Building Native Components section.
• Administrative privilege may be required to extract Ghidra to certain filesystem destinations (such as C:\), as well as install the Ghidra Server as a service.
• Ghidra relies on using directories outside of its installation directory to manage both temporary and longer-living cache files. Ghidra attempts to use standard OS directories that are designed for these purposes in order to avoid several issues, such as storing large amounts of data to a roaming profile. If it is suspected that the default location of these directories is causing a problem, they can be changed by modifying the relevant properties in the support/launch.properties file.

Java Notes

• Ghidra requires a supported version of a Java Runtime and Development Kit on the PATH to run. However, if there is a version of Java on the PATH that Ghidra does not support, it will use that version of Java (if 1.8 or later) to assist in locating a supported version on your system. If one cannot be automatically located, the user will be prompted to enter a path to the Java home directory to use (the Java home directory is the parent directory of Java's bin directory). This minimizes the impact Ghidra has on pre-existing configurations of Java that other software may rely on.
• Depending on your operating system, it may be possible to find and install a supported version of a Java Runtime and Development Kit through your package manager, without the need to set the Path environment variables as described below.
• If Ghidra failed to run because no versions of Java were on the PATH, a supported JDK should be installed via a Linux package manager (aptitude, yum, etc), Windows installer program (*.exe, *.msi), macOS Installer package (*.pkg), or manually extracted and added to the PATH. The following steps outline how to manually extract and add a JDK distribution to the operating system's PATH.

  • Windows: Extract the JDK distribution (.zip file) to your desired location and add the JDK's bin directory to your PATH:

    1. Extract the JDK:

       1. Right-click on the zip file and click Extract All...
       2. Click Extract

    2. Open Environment Variables window:

       1. Right-click on Windows start button, and click System
       2. Click Advanced system settings
       3. Click Environment variables...

    3. Add the JDK bin directory to the PATH variable:

       1. Under System variables, highlight Path and click Edit...
       2. At the end of the the Variable value field, add a semicolon followed by <path of extracted JDK dir>\bin, or use the New button in the Edit environment variable window to add a new entry to the Path.
       3. Click OK
       4. Click OK
       5. Click OK
    4. Restart any open Command Prompt windows for changes to take effect

  • Linux and macOS (OS X): Extract the JDK distribution (.tar.gz file) to your desired location, and add the JDK's bin directory to your PATH:

    1. Extract the JDK:

       tar xvf <JDK distribution .tar.gz>

    2. Open ~/.bashrc with an editor of your choice. For example:

       vi ~/.bashrc

    3. At the very end of the file, add the JDK bin directory to the PATH variable:

       export PATH=<path of extracted JDK dir>/bin:$PATH

    4. Save file
    5. Restart any open terminal windows for changes to take effect
• In some cases, you may want Ghidra to launch with a specific version of Java instead of the version that Ghidra automatically locates. To force Ghidra to launch with a specific version of Java, set the JAVA_HOME_OVERRIDE property in the support/launch.properties file. If this property is set to an incompatible version of Java, Ghidra will revert to automatically locating a compatible version. Note that some Java must still be on the PATH in order for Ghidra to use the JAVA_HOME_OVERRIDE property. This limitation will be addressed in a future version of Ghidra.

(Back to Top)

Ghidra Installation Directory Layout

When Ghidra is installed, the runnable software gets extracted to a new directory we will refer to as <GhidraInstallDir>. Below is a description of the top-level directories and files that can be found in <GhidraInstallDir> once extraction of the distribution file is complete.

(Back to Top)

Building Native Components

Ghidra requires several native binaries to be present in order to successfully run. An official public Ghidra release includes native binaries for the following platforms.

NOTE: For some non-public Ghidra releases macOS natives may be omitted.

• Windows 10 or later, x86 64-bit
• Windows 10 or later, ARM 64-bit (using x86 emulation)
• Linux x86 64-bit
• macOS x86 64-bit
• macOS ARM 64-bit

Ghidra supports running on the following additional platforms with user-built native binaries:

• Linux ARM 64-bit
• FreeBSD x86 64-bit (no debugger support)
• FreeBSD ARM 64-bit (no debugger support)

For supported systems where native binaries have not been supplied, or those that are supplied fail to run properly, it may be necessary to build the native Ghidra binaries. In order to build native binaries for your platform, you will need the following installed on your system:

• A supported version of a Java Development Kit
• Gradle 8.5+ (or supplied Gradle wrapper with Internet connection)
• Software C/C++ build tools and library packages
• macOS: Xcode or the abbreviated Command Line Tools for Xcode will supply the necessary build tools. Assuming you are connected to the Internet, Xcode (which includes the command tools) may be installed directly from the App Store while Command Line Tools for Xcode may be installed using the following command:

      xcode-select --install

• Linux/FreeBSD: the 64-bit versions of the following packages should installed:
  • gcc 8.5 or later
  • gcc-c++ / g++ 8.5 or later
  • make
• Windows: Microsoft Visual Studio 2017 or later, or Microsoft C++ Build Tools with the following components installed:
  • MSVC
  • Windows SDK
  • C++ ATL

To build the native binaries for your current platform, execute the following commands:

    cd <GhidraInstallDir>/support/gradle/
    gradle buildNatives
  

If you are connected to the Internet and do not have Gradle installed, execute:

    cd <GhidraInstallDir>/support/gradle/
    ./gradlew(.bat) buildNatives
  

When the commands successfully complete, Ghidra will contain newly built native binaries in the relevant modules' build/os/<platform>/ subdirectories, which will override any existing pre-built native binaries in the os/<platform>/ subdirectories.

(Back to Top)

Installing the Debugger's Python Dependencies

The Debugger now uses Python to connect to the host platform's native debuggers. This requires Python3 (3.9 to 3.12) and some additional packages. These packages are included in the distribution, but you may still install them from PyPI if you prefer:

• psutil
• protobuf==3.20.3
• Pybag>=2.2.10 (for WinDbg support)

Different native debuggers have varying requirements, so you do not necessarily have to install all of the above packages. Each connector will inform you of its specific requirements and where they must be installed. In some cases, you may need to install packages on the target system.

Running Ghidra

GUI Mode

1. Navigate to <GhidraInstallDir>

2. Run ghidraRun.bat (Windows) or ghidraRun (Linux or macOS)

   If Ghidra failed to launch, see the Troubleshooting section.

Ghidra Server

Ghidra can support multiple users working together on a single project. Individual Ghidra users launch and work on their own local copies of a particular Ghidra project but check changes into a common repository containing all commits to that repository. For detailed information on installing/configuring the Ghidra Server see the <GhidraInstallDir>/server/svrREADME.html file.

Headless (Batch) Mode

Ghidra is traditionally run in GUI mode. However, it is also capable of running in headless batch mode using the command line. For more information, see the <GhidraInstallDir>/support/analyzeHeadlessREADME.html file.

Single Jar Mode

Normally, Ghidra is installed as an entire directory structure that allows modular inclusion or removal of feature sets and also provides many files that can be extended or configured. However, there are times when it would be useful to have all or some subset of Ghidra compressed into a single jar file at the expense of configuration options. This makes Ghidra easier to run from the command line for headless operation or to use as a library of reverse engineering capabilities for another Java application.

A single ghidra.jar file can be created using the <GhidraInstallDir>/support/buildGhidraJar script.

(Back to Top)

Extensions

Extensions are optional components that can:

• Extend Ghidra's functionality with experimental or user-contributed Ghidra plugins or analyzers.
• Integrate other tools with Ghidra, such as Eclipse or IDAPro.

Ghidra comes with the following extensions available for use (and by default uninstalled), which can be found in the <GhidraInstallDir>/Extensions directory.

• Eclipse: The GhidraDev Eclipse plugin for a pre-existing Eclipse installation. For information on installing and using the GhidraDev Eclipse plugin, see <GhidraInstallDir>/Extensions/Eclipse/GhidraDev/GhidraDev_README.html.
• Ghidra: Ghidra extensions (formerly known as contribs). See Ghidra Extension Notes for more information.
• IDAPro: IDAPro plugins/loaders for transferring items with Ghidra.

Ghidra Extension Notes

• Ghidra extensions are designed to be installed and uninstalled from the Ghidra front-end GUI:

  1. Click File → Install Extensions
  2. Check boxes to install extensions; uncheck boxes to uninstall extensions
  3. Restart Ghidra for the changes to take effect
• Extensions installed from the Ghidra front-end GUI get installed at <UserSettings>/Extensions, where <UserSettings> can be looked up in the Ghidra front-end GUI under Help -> Runtime Information -> Application Layout -> Settings Directory.

• It is possible to install Ghidra extensions directly into the Ghidra installation directory. This may be required if a system administrator is managing extensions for multiple users that all use a shared installation of Ghidra. It may also be more convenient to manage extensions this way if a Ghidra installation is only ever used headlessly.

  To install an extension in these cases, simply extract the desired Ghidra extension archive file(s) to the <GhidraInstallDir>/Ghidra/Extensions directory. For example, on Linux or macOS:

  1. Set current directory to the Ghidra installed-extensions directory:

  cd <GhidraInstallDir>/Ghidra/Extensions

  2. Extract desired extension archive file(s) to the current directory:

  unzip ../../Extensions/Ghidra/<extension>.zip

  3. The extension(s) will be installed the next time Ghidra is started.

  To uninstall extensions, simply delete the extracted extension directories from <GhidraInstallDir>/Ghidra/Extensions. The extension(s) will be uninstalled the next time Ghidra is started.

  NOTE: It may not be possible to uninstall an extension in this manner if there is an instance of Ghidra running that holds a file lock on the extension directory that is trying to be deleted.