The information provided in this document is effective as of Ghidra 11.4 and is subject to change with future releases.
NOTE: All 32-bit OS installations are now deprecated. Please contact the Ghidra team if you have a specific need.
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).
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:
xattr -d com.apple.quarantine ghidra_<version>_<date>.zip
from a terminal.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.
Ghidra requires a supported version of a Java Runtime and Development Kit
on the PATH, or specified by the JAVA_HOME environment variable. If JAVA_HOME is specified
it will take precedence over the PATH. If the version of Java found does not satisfy the
minimum version required, 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:
Extract All...
Extract
System
Advanced system settings
Environment variables...
System variables
, highlight Path
and click Edit...
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
.OK
OK
OK
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:
tar xvf <JDK distribution .tar.gz>
~/.bashrc
with an editor of your choice. For example:
vi ~/.bashrc
export PATH=<path of extracted JDK dir>/bin:$PATH
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 or specified by JAVA_HOME
environment variable in order for Ghidra to use the JAVA_HOME_OVERRIDE
property.
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.
For more information, see <GhidraInstallDir>/docs/GhidraClass/Debugger/A1=GettingStarted.html
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.
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:
xcode-select --install
.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.
<GhidraInstallDir>
ghidraRun.bat
(Windows) or ghidraRun
(Linux or macOS)If Ghidra failed to launch, see the Troubleshooting section.
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.
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.
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.
Ghidra has integrated 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.
<GhidraInstallDir>/support/
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
.
BSim is a Ghidra plugin for finding structurally similar functions in collections of binaries.
For more information, see <GhidraInstallDir>/docs/GhidraClass/BSim/BSimTutorial_Intro.html
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:
GhidraDev
and GhidraSleighEditor
Eclipse plugins for a pre-existing Eclipse
installation. For information on installing and using the GhidraDev
Eclipse plugin, see
<GhidraInstallDir>/Extensions/Eclipse/GhidraDev/README.html
.Ghidra extensions are designed to be installed and uninstalled from the Ghidra front-end GUI:
File -> Install Extensions
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:
cd <GhidraInstallDir>/Ghidra/Extensions
unzip ../../Extensions/Ghidra/<extension>.zip
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.
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
.
.rep
directory and .gpr
file from any Ghidra project
directories to a safe location on your file system.Tools -> Default Tools...
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.Please refer to the <GhidraInstallDir>/server/svrREADME.html
file for details on upgrading your
Ghidra Server.
When launching Ghidra with the provided scripts in <GhidraInstallDir>
and
<GhidraInstallDir>/support
, you may encounter the following error messages:
Problem: The 'java' command could not be found in your PATH or with JAVA_HOME.
Problem: Failed to find a supported JDK.
Problem: Exited with error. Run in foreground (fg) mode for more details.
LAUNCH_MODE
variable in the launch script you ran to fg
. Alternatively, you can use the
<GhidraInstallDir>/support/ghidraDebug
script to run Ghidra in debug mode, which will also
allow you to see the error message as well as additional debug output.
NOTE: By default, running Ghidra in debug mode listens on 127.0.0.1:18001
.There are several ways you can get help with using Ghidra:
<GhidraInstallDir>/docs
.F1
. Help for that
window/menu/component will be displayed.Help -> Topics...
!
character. This is to avoid issues that
Java's internal libraries have parsing these paths (!
is used as a jar-separator by Java).^
character.VMARGS=-Dsun.java2d.opengl
to true
in <GhidraInstallDir>/support/launch.properties
may fix
this issue.<GhidraInstallDir>/Extensions/Eclipse/GhidraDev/README.html
for more information on
building Ghidra module extensions from Eclipse.