Ghidra Installation Guide

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

Table of Contents

  1. Platforms Supported
  2. Minimum Requirements
  3. Installing Ghidra
  4. Ghidra Installation Directory Layout
  5. Building Native Components
  6. Running Ghidra
  7. Extensions
  8. Ghidra Development
  9. Upgrade Instructions
  10. Troubleshooting and Help
  11. Known Issues

Platforms Supported

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

Minimum Requirements

Hardware

Software

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

Java Notes

Debugger Notes

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

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.

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.

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:

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

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:

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 Ghidra will prefer to any existing pre-built native binaries in the os/<platform>/ subdirectories.

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.

PyGhidra Mode

Ghidra has integrated the the popular Pyhidra extension to enable native CPython 3 support out of the box. To enable this support, Ghidra must be launched from a Python environment using special launch scripts.

  1. Navigate to <GhidraInstallDir>/support/
  2. Run pyghidraRun.bat (Windows) or pyghidraRun (Linux or macOS).

If the pyghidra Python module has not yet been installed, the script will offer to install it for you, along with its dependencies. If you prefer to install it manually, execute:

python3 -m pip install --no-index -f <GhidraInstallDir>/Ghidra/Features/PyGhidra/pypkg/dist pyghidra

NOTE: You may also install and run PyGhidra from within a virtual environment if you desire.

If Ghidra failed to launch, see the Troubleshooting section.

Once PyGhidra has been installed, you are free to use it like any other Python module. You may import it from other Python scripts, or launch PyGhidra using the pyghidra or pyghidraw commands. For more information on using PyGhidra, see <GhidraInstallDir>/Ghidra/Features/PyGhidra/README.html.

Extensions

Extensions are optional components that can:

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

Ghidra Extension Notes

Ghidra Development

Users can extend the functionality of Ghidra through the development of custom Ghidra scripts, plugins, analyzers, etc.

Ghidra supports development in Eclipse by providing a custom Eclipse plugin called GhidraDev, which can be found in the <GhidraInstallDir>/Extensions/Eclipse directory. For more information on installing and using the GhidraDev Eclipse plugin, see <GhidraInstallDir>/Extensions/Eclipse/GhidraDev/README.html.

NOTE: Eclipse is not provided with Ghidra. The GhidraDev Eclipse plugin is designed to be installed in a pre-existing Eclipse installation.

Ghidra scripting API javadocs can be found at <GhidraInstallDir>/docs/GhidraAPI_javadoc.zip.

Upgrade Instructions

General Upgrade Instructions

  1. !!!Important!!! BACKUP YOUR OLD PROJECTS FIRST!!
  2. New installations of Ghidra will, by default, use the saved profile from a user's most recent version of Ghidra. This allows any saved tool configurations to be automatically ported to new projects. However, this may also prevent new tool options and features from automatically being configured in some cases. To open new tools containing the latest configurations, users should, from the Project Manager Window, choose Tools -> Default Tools...
  3. When you open a program that was created using a previous version of Ghidra, you will be prompted to upgrade the program before it can be opened. The upgrade will not overwrite your old file until you save it. If you save it (to its original file), you will no longer be able to open it using an older version of Ghidra. You could, however, choose to perform a Save As instead, creating a new file and leaving the old version unchanged. Be very careful about upgrading shared program files since everyone accessing the file must also upgrade their Ghidra installation.

Server Upgrade Instructions

Please refer to the <GhidraInstallDir>/server/svrREADME.html file for details on upgrading your Ghidra Server.

Troubleshooting and Help

Launching Ghidra

When launching Ghidra with the provided scripts in <GhidraInstallDir> and <GhidraInstallDir>/support, you may encounter the following error messages:

Using Ghidra

There are several ways you can get help with using Ghidra:

Known Issues

All Platforms

Windows

Linux

macOS