Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Installing Apache JMeter on Windows, macOS and Linux

Install Apache JMeter step by step: check Java, download and unpack the binary, start the GUI or command line, set memory, and verify the installation on any OS.

JMeter needs no installer. It is a ZIP or TGZ archive that you unpack, plus a Java runtime. That makes setup quick and also makes it easy to keep several versions side by side. This lesson covers the prerequisites, downloading, launching, and the first configuration changes worth making.

Honesty note. The commands below are what you type on your own computer; nothing here runs on the website. Version numbers change, so check the official download page for the current release and the Java version it requires. The runnable block is a stand-in that checks a version string the way a script might.

Step 1: Check Java

JMeter is a Java application, so it needs a Java Runtime Environment (JRE) or a full JDK. Recent JMeter 5.x releases run on Java 8 or newer; newer major versions may raise this, so read the release notes. Check your installation in a terminal:

Terminal
java -version

If you see a version number, Java is installed. If the command is not found, install a free OpenJDK build (for example Eclipse Temurin) and open a new terminal. If you plan to write Groovy scripts and use plugins that compile code, install a JDK rather than a bare JRE.

On Windows, make sure the JAVA_HOME environment variable points to the JDK folder, or that java is on the PATH. JMeter's start script uses whichever java it finds first.

Step 2: Download JMeter

From the Apache JMeter download page, take the binaries archive (apache-jmeter-X.Y.zip or .tgz). Do not take the "source" archive. Optionally verify the file against the published SHA-512 checksum or PGP signature, which proves the download is intact and authentic.

Unpack the archive to a path without spaces, for example C:\tools\apache-jmeter-5.6.3 on Windows or ~/tools/apache-jmeter-5.6.3 elsewhere. Paths with spaces cause surprises in scripts.

Step 3: Look inside the folder

Folder or file Purpose
bin/jmeter.bat, bin/jmeter Starts the GUI (Windows and Unix scripts)
bin/jmeter-n.cmd, jmeter-server Non-GUI shortcut, and the server for distributed tests
bin/jmeter.properties Main settings (do not edit directly; see below)
bin/user.properties Your overrides: safe place for changes
bin/templates/ Ready-made test plan templates
lib/ Core libraries; drop JDBC drivers here
lib/ext/ JMeter plugins (JARs)
docs/, printable_docs/ Offline documentation
extras/ Ant build files and helpers

Rule of thumb: put your own settings in user.properties so an upgrade does not overwrite them.

Step 4: Start JMeter

GUI mode (for building plans):

Terminal
# Windows
bin\jmeter.bat

# macOS or Linux
./bin/jmeter

The first launch shows a window with an empty Test Plan in the left tree. A warning about GUI mode in the log reminds you that real tests should run from the command line.

Non-GUI mode (for load):

Terminal
./bin/jmeter -n -t plans/shop.jmx -l results/run1.jtl

The most-used command-line options are:

Option Meaning
-n Non-GUI mode
-t file.jmx Test plan to run
-l file.jtl Write sample results here
-j file.log Write the JMeter log here
-e -o folder Generate the HTML dashboard into an empty folder after the run
-J name=value Set a JMeter property for this run
-G name=value Send a property to remote servers
-r / -R host1,host2 Run on all or chosen remote servers
-H host -P port Use a proxy for the test's HTTP traffic

Unix users: you might need chmod +x bin/jmeter if the execute bit was lost.

Step 5: Give JMeter enough memory

JMeter's startup script reads the HEAP environment variable. The default is small (1 GB in recent releases). For bigger tests set it before starting:

Terminal
# Linux/macOS
export HEAP="-Xms2g -Xmx4g -XX:MaxMetaspaceSize=256m"
./bin/jmeter -n -t plans/shop.jmx -l results/run1.jtl

On Windows, use set HEAP=-Xms2g -Xmx4g in the same console. Never give JMeter more than about 80% of the machine's free memory, and keep the heap minimum and maximum equal for steady garbage collection.

Step 6: Verify the installation

Quick checks:

  1. bin/jmeter --version prints a banner with the version (and exits).
  2. The GUI opens; Help > About shows the version and Java.
  3. Options > Look and Feel lets you pick a dark theme if you wish.
  4. Create a tiny plan (see Your first test plan) and run it against a site you own.

The stand-in below shows how a script could check that a reported Java version is new enough. This is the same kind of guard teams put in CI setup scripts.

JS Stand-in: parse and compare a Java version string

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Plugins and the Plugins Manager

JMeter's capabilities grow with plugins. The community JMeter Plugins Manager is a single JAR you drop into lib/ext/; after a restart, Options > Plugins Manager lets you install extras such as extra graphs, the Ultimate Thread Group and the Throughput Shaping Timer. Install only what you need, and re-check compatibility after upgrading JMeter.

Folder layout for your own work

Do not store plans inside the JMeter folder. A layout that scales:

TEXT
perf-tests/
โ”œโ”€โ”€ plans/        shop.jmx, api.jmx
โ”œโ”€โ”€ data/         users.csv, products.csv
โ”œโ”€โ”€ results/      run-2025-01-10.jtl (not committed)
โ”œโ”€โ”€ reports/      html dashboards (not committed)
โ””โ”€โ”€ README.md     how to run

Keep JMeter itself in ~/tools/ and call it by full path or put its bin on the PATH.

Troubleshooting

  • Window opens and closes at once: run the script from a terminal to see the error; usually Java is missing or too old.
  • OutOfMemoryError: raise HEAP, or reduce listeners and stored response data.
  • Blurry fonts on high-DPI screens: set jmeter.hidpi.mode=true and a scale factor in user.properties.
  • Corporate proxy blocks the Plugins Manager: start JMeter with -H and -P options or download plugin JARs manually.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does JMeter need installed on your computer besides the unpacked archive?

    JMeter is written in Java and starts through a JVM; no installer or database is required.
  2. 2. Where should your own property changes go so upgrades do not overwrite them?

    user.properties overrides jmeter.properties and is meant for your own settings.
  3. 3. Which command runs a plan without the GUI and saves results?

    -n selects non-GUI mode, -t names the test plan and -l the results file.
  4. 4. Where do JDBC driver JARs go?

    Drivers are placed in lib (or lib/ext for plugins) and JMeter is restarted so the classes load.

Summary

  • Install Java, download the binaries archive, unpack it to a path without spaces.
  • bin/jmeter starts the GUI; jmeter -n -t plan.jmx -l out.jtl runs non-GUI.
  • Put overrides in user.properties, drivers in lib/, plugins in lib/ext/.
  • Raise memory with the HEAP environment variable for big tests.
  • Keep plans, data and results in your own project folder, not inside JMeter.

Next: Your First Test Plan