# Apache Hop requirements, installation and configuration ## Apache Hop requirements, installation and configuration ### Overview The requirements and installation process for Apache Hop are intentionally kept as simple as possible. This page covers everything you need to know to install and run Apache Hop on your local desktop or server, from the very basics to more advanced configurations. Hop is designed to be as flexible and lightweight as possible, and is intended to blend in with your architecture, not the other way around. This makes the basic installation process extremely easy, but there’s a lot of configuration that can be applied to make Hop behave exactly the way you want it to. | Tip | Take a look at the [Docker](tech-manual::docker-container.xJkU76Vk0i) page for instructions to run Hop in containers and Kubernetes environments. | | --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ### System Requirements Hop’s limited footprint should allow it to run on any modern physical or virtual machine. For the default Hop distribution, a minimum of 1 CPU/core and 4GB RAM should do, even though you can tweak Hop to run on machines with even less memory. Hop Runs on the following operating systems: * Windows 7 or higher * Linux (x86\_64, ARM) * MacOS * any modern browser (Hop Web) ### Java Runtime The only requirement Hop has on any supported operating system is the Java Runtime environment. Apache Hop is known to work well on the following widely used Java Runtimes: * [Oracle Java Runtime](https://www.java.com/) * [Microsoft OpenJDK](https://www.microsoft.com/openjdk) (OpenJDK builds for Windows, MacOS and Linux). * [OpenJDK Java Runtime](https://openjdk.java.net/install/) Apache Hop works well with these 64-bit java runtimes for version 11. Other Java Runtimes may work but haven’t been used and tested as extensively as the Oracle and OpenJDK JREs, so you may be pioneering. Feel free to open a [GitHub ticket](https://hop.apache.org/community/tools/#GitHub-Issues) if you run into issues, but please mention your JRE and version. Run `java -version` if you’re not sure which Java version is currently installed on your system. Your output should be similar to the one shown below. ```highlight openjdk version "11.0.2" 2019-01-15 OpenJDK Runtime Environment 18.9 (build 11.0.2+9) OpenJDK 64-Bit Server VM 18.9 (build 11.0.2+9, mixed mode) ``` Make sure to point the `JAVA_HOME` environment variable for your operating system to your desired JRE installation. Refer to your operating system’s documentation for more information on environment variables. ### Basic Installation The basic installation for Apache Hop couldn’t be easier: * [download](https://hop.apache.org/download/) * unzip * change to your newly unzipped `hop` directory * run: * `hop-gui.bat` (Windows) or `hop-gui.sh` (Linux, MacOS): run [Hop Gui](https://github.com/mbertazz/hop-docs-md/blob/main/modules/ROOT/pages/hop-gui/index.xJkU76Vk0i) * `hop-run.bat` (Windows) or `hop-run.sh` (Linux, MacOS): [run workflows or pipelines](https://github.com/mbertazz/hop-docs-md/blob/main/hop-run/index.xJkU76Vk0i) from the command line. * `hop-server.bat` (Windows) or `hop-server.sh` (Linux, MacOS): start a [Hop Server](https://github.com/mbertazz/hop-docs-md/blob/main/hop-server/index.xJkU76Vk0i) instance. ### Set (system) environment variables Apache Hop’s installation and configuration are fully self-contained by default. With the system or environment variables below, you can make your Hop configuration independent of the installed Hop versions. This lets you switch between Hop versions or installations, while keeping your projects and environment lists, last opened files and other settings. | Tip | if you set the environment variables below after you’ve been using Apache Hop for a while, you can move the contents of your `hop/config/` folder to your new `HOP_CONFIG_FOLDER` location | | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | #### Create environment variables in Windows There are several ways to access the Environment Variables in Windows. One ways is to search for `environment variable` in the start menu and clicking the "Edit the system environment variables" link (or the corresponding entry for your local language). ![Access environment variables from the start mennu](/files/AZsmxfwGpiTLY25i0WVs) In the dialog that pops up, click the `Environment Variables` button, then add a new `HOP_CONFIG_FOLDER` user variable and point it to the folder where you’d like to store your Apache Hop configuration. Repeat the process for any of the other variables list below you want to add to your configuration. ![Set environment variables](/files/DXCfAthafLaEJAg4rYZ2) Click `Ok` to close the dialogs and (re)start Hop Gui to activate the environment variables. #### Create environment variables in Mac OS or Linux Add environment variables to your `~/.bashrc`, `~/.zshrc` or similar configuration file as shown below: `export HOP_CONFIG_FOLDER=`. run `source ~/.bashrc` or `source ~/.zshrc` to apply the new variables in your current session. #### The environment variables to set Unresolved directive in tmp.lQZSo9ZXhY - include::snippets/variables/hop-config-folder.adoc\[] Unresolved directive in tmp.lQZSo9ZXhY - include::snippets/variables/hop-audit-folder.adoc\[] Unresolved directive in tmp.lQZSo9ZXhY - include::snippets/variables/hop-options.adoc\[] Check the [Environment Variables](#envvars) section for more system variables that can make your life with multiple Hop versions or installations a lot easier. ### Upgrade Multiple Hop versions can be installed side by side with the same process as described in the [Basic Installation](#basic). Hop installations are self-contained by default, which means you’ll start with the default configuration and project and environment list with after new Hop install. With the environment variables described in the previous section, all you need to do to upgrade Apache Hop next to your existing hop installation and start Hop Gui from there. Your projects and environment lists, last opened files etc should all be available. | Tip | Apache Hop releases are tested for smooth upgrades. You can replace your existing installation when a new version is released. If you want to keep multiple Apache Hop versions around, consider renaming your unzipped `hop` folder to `hop-version-number`, e.g. `hop-2.5.0`, `hop-2.60` etc. | | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ### Additional configuration #### JVM memory settings By default, Hop only sets a maximum for the JVM Heap size Hop can allocate. This parameter can be changed in the `hop-gui.bat` or `hop-gui.sh` or similar scripts for `hop-run` and `hop-server`. Identify the following line: `HOP_OPTIONS="-Xmx2048m"` The `-Xmx` parameter determines the maximum amount of memory the JVM can allocate and can be specified in MB or GB. For example: * `HOP_OPTIONS=-Xmx512m`: start Hop with maximum **512MB** of memory * `HOP_OPTIONS=-Xmx2048m`: start Hop with maximum **2048MB** (or 2GB) of memory * `HOP_OPTIONS=-Xmx4g`: start Hop with maximum **4GB** of memory Check the documentation for your JRE for more information about additional JVM configuration, tuning and garbage collection parameters. [This guide](https://www.baeldung.com/jvm-parameters) may help you to get started. | Tip | **Developers**: a couple of lines below the `-Xmx` parameter, you’ll find another `HOP_OPTIONS` line that contains `-Xdebug`. Uncomment this line to allow debuggers to attach to your running Hop instance. Check the [developer documentation](dev-manual::setup-dev-environment.xJkU76Vk0i) for more information. | | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### Hop environment variables The following (operating system) environment variables can add a lot of flexibility to configure Hop to your exact needs. Unresolved directive in tmp.lQZSo9ZXhY - include::snippets/variables/hop-audit-folder.adoc\[] Unresolved directive in tmp.lQZSo9ZXhY - include::snippets/variables/hop-config-folder.adoc\[] Unresolved directive in tmp.lQZSo9ZXhY - include::snippets/variables/hop-plugin-base-folders.adoc\[] Unresolved directive in tmp.lQZSo9ZXhY - include::snippets/variables/hop-shared-jdbc-folder.adoc\[] #### JDBC Drivers, Jars, Libraries, and other plugin dependencies Hop comes with built-in support for tens of databases and a large number of other technologies. Depending on the Apache and technology vendor’s licenses, the required libraries may not be available in the default Apache Hop distribution. Download the necessary drivers or other required libraries and add them to your plugin’s `lib` directory. For example, to add a JDBC driver for the MySQL database, download the MySQL JDBC jar file and add it to `/hop/plugins/databases/mysql`. Add any custom jars in `lib/core` in your Hop installation folder to make those libraries available for your entire Hop installation. Add any custom jars to `plugins/transforms/janino/lib` to make them available for the User Defined Java Class transform. #### Technology configuration Hop comes with built-in support for lots of technologies that may require their own (installation and) configuration. Check the [technology](https://github.com/mbertazz/hop-docs-md/blob/main/modules/ROOT/pages/technology/technology.xJkU76Vk0i) page for the platform you need to configure to find out more. Last updated 2025-09-04 18:21:06 +0200 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.primeur.com/data-shaper-1.21/esclusi/installation-configuration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.