# Getting Started with Ghidra
The information provided in this document is effective as of Ghidra 12.1 and is subject to change 
with future releases.

## Table of Contents
 1. [Platforms Supported](#platforms-supported)
 2. [Minimum Requirements](#minimum-requirements)
    * [Hardware](#hardware)
    * [Software](#software)
 3. [Installing Ghidra](#installing-ghidra)
    * [Installation Notes](#installation-notes)
    * [Java Notes](#java-notes)
    * [Debugger Notes](#debugger-notes)
 4. [Ghidra Installation Directory Layout](#ghidra-installation-directory-layout)
 5. [Building Native Components](#building-native-components)
 6. [Running Ghidra](#running-ghidra)
    * [GUI Mode](#gui-mode)
    * [Ghidra Server](#ghidra-server)
    * [Headless (Batch) Mode](#headless-batch-mode)
    * [Single Jar Mode](#single-jar-mode)
    * [PyGhidra Mode](#pyghidra-mode)
    * [Behavioral Similarity (BSim)](#behavioral-similarity-bsim)
 7. [Extensions](#extensions)
    * [Ghidra Extension Notes](#ghidra-extension-notes)
 8. [Ghidra Development](#ghidra-development)
 9. [Upgrade Instructions](#upgrade-instructions)
    * [General Upgrade Instructions](#general-upgrade-instructions)
    * [Server Upgrade Instructions](#server-upgrade-instructions)
10. [Troubleshooting and Help](#troubleshooting-and-help)
    * [Launching Ghidra](#launching-ghidra)
    * [Using Ghidra](#using-ghidra)
11. [Known Issues](#known-issues)
    * [All Platforms](#all-platforms)
    * [Windows](#windows)
    * [Linux](#linux)
    * [macOS](#macos)

## Platforms Supported
* Windows 10 (build 1809 or later)
* Linux
* 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](#java-notes))
  * Free long term support (LTS) versions of JDK 21 are provided by:
    * [Adoptium Temurin](https://adoptium.net/temurin/releases)
    * [Amazon Corretto](https://docs.aws.amazon.com/corretto/latest/corretto-21-ug/downloads-list.html)
* Python3 (3.9 to 3.14)
  * Python 3.9 to 3.14 for [Debugger support](#debugger-notes)
  * Python 3.9 to 3.14 for [PyGhidra support](#pyghidra-mode)
  * This is available from [Python.org](https://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 with pip support.

## 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).

__NOTE:__ Do not extract Ghidra on top of an existing installation.

### 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](#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](#minimum-requirements) 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](#minimum-requirements) 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](#minimum-requirements) 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](#minimum-requirements) 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 `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