Installation & Configuration

Check the runtime before anything else:

Typical output:

Source: Getting Started: Java requirements and installation (User Manual)

The binaries are published at the official download page. For 5.6.3 the files are apache-jmeter-5.6.3.tgz and apache-jmeter-5.6.3.zip (binaries) and apache-jmeter-5.6.3_src.tgz and apache-jmeter-5.6.3_src.zip (sources). Every file has a matching .sha512 checksum file and a .asc PGP signature. The page insists that the integrity of downloads must be verified with the PGP signature, and links to the Apache project’s guide on verifying releases. The signing keys are published in the KEYS file at https://www.apache.org/dist/jmeter/KEYS.

Why it matters on a load generator: the machine will run arbitrary test plans and often sits inside a corporate or cloud network. A tampered archive is a supply-chain risk, and checking takes less than a minute.

The exact download mirror URLs change; take them from the download page rather than from a script written months ago. shasum -a 512 (macOS) is sha512sum on Linux, and on Windows certutil -hashfile apache-jmeter-5.6.3.zip SHA512 gives the digest. A good signature reports Good signature from a JMeter committer; a warning that the key is not certified means only that you have not set a trust level for it, not that the file is bad. BAD signature means do not use the file. The checksum is fetched from the main Apache site so that it does not depend on the mirror that served the archive.

Source: Download Apache JMeter

Then unpack it. The manual recommends avoiding spaces in the installation path, which can cause trouble, particularly in client-server (distributed) mode, and allows renaming the top-level apache-jmeter-X.Y directory but not any of its subdirectories.

On Windows, unzip apache-jmeter-5.6.3.zip to a path without spaces, such as C:\tools\apache-jmeter-5.6.3, and add its bin directory to PATH.

Source: Getting Started: Installing JMeter (User Manual)

The unpacked directory is called JMeter’s home. The directories below are the ones the manual describes; bin/templates is described on the templates page.

The manual’s table lists bin, docs, extras, lib, lib/ext, lib/junit, licenses and printable_docs; the description of what extras contains is deliberately general because the manual gives only "additional files". jmeter.log is created in the directory the script was launched from, not in bin, unless the log file is redirected (see Logging below). Always start scripts from a working directory you control, such as the project’s test directory, so that the log and any relative paths (CSV files, result files) resolve there.

Source: Getting Started: Installing JMeter (User Manual), Creating Templates

Two rules shape everything that follows. First, the GUI is for creating, debugging and checking scripts; load must be generated in CLI mode (-n), which is covered in the page on running tests in CLI mode. Second, anything that behaves differently when started from a launcher script and when started with java -jar ApacheJMeter.jar (JVM options, language, GC) comes from the script, so always use the script.

Source: Getting Started: Running JMeter (User Manual)

The scripts read environment variables, so no script has to be edited. The ones the manual documents:

On Windows the scripts additionally use DDRAW (direct-draw options, empty by default) and JM_LAUNCH (the Java executable, java.exe by default or javaw.exe).

Settings you want on every run go in a file that the script sources: bin/setenv.sh on Unix (the jmeter script sources it) or bin\setenv.bat on Windows. Settings for one run go on the command line.

For Windows the manual’s example for bin\setenv.bat is set JVM_ARGS=-Xms1024m -Xmx1024m -Dpropname=value.

Sizing the heap: worked reasoning. The manual does not give a threads-per-gigabyte figure, and any such number depends on the plan, so measure. A method that works: run the real plan at the planned thread count with the default 1 GiB heap and watch garbage-collection behaviour (enable -Xlog:gc* through JVM_ARGS on Java 9+). If a full-heap collection occurs often or an OutOfMemoryError appears in jmeter.log, double HEAP and repeat. Keep -Xms equal to -Xmx so the heap does not resize during the test, and keep the heap below the machine’s free RAM minus the operating system and any co-located tools, otherwise the load generator swaps and the test measures the generator rather than the system under test. Heap, listeners, assertions and response-body retention are what drive memory; the page on best practices and load-generator tuning goes into these.

GUI mode costs far more than CLI mode because every sampler result can be kept by a listener in memory. Never run a load test from the GUI, and do not size the heap from a GUI trial.

Source: Getting Started: JVM options and environment variables (User Manual)

JMeter reads three property files from bin:

The manual gives the load order: the -p option is read first, then jmeter.properties (or the file given with -p) is loaded; then the -j log file is set; logging is initialised; then user.properties is loaded; then system.properties; and finally all other command-line options are processed. -q additional property files and -J properties are handled after user.properties, and -S and -D after system.properties. The practical consequence is that a later source wins: -Jthreads=20 on the command line overrides threads=10 in user.properties, which in turn overrides the default in jmeter.properties.

A parameterised run, with the property read inside the plan by the ${__P(threads,10)} function (properties and functions are covered on the page about properties, variables and functions):

With those arguments threads is 50 and rampup 120, while anything else comes from user.properties. Passing a property on the command line is visible to other users who can list processes, a warning the manual makes; do not pass secrets that way.

Source: Getting Started: Overriding properties (User Manual), Properties Reference

JMeter is started with java -jar, so the CLASSPATH environment variable has no effect. The ways to add code are:

JDBC and JMS jars are not bundled. The JDBC Connection Configuration element fails with a class-not-found error until the driver jar for your database is in lib (or on one of the paths above). The same is true for JMS provider client libraries. Get the jars from the vendor.

Restart JMeter after changing any of these. A frequent mistake is dropping a library into lib/ext, where JMeter scans it for components, wasting startup time and sometimes loading it in the wrong class loader. Planned JMeter 6.0 changes in the way plugins are loaded are not detailed in the official documentation; in 5.6 plugins can also be found through Java’s ServiceLoader mechanism.

Source: Getting Started: Classpath configuration (User Manual), Getting Started: JDBC drivers

Since JMeter 3.2, logging uses Apache Log4j 2 and is configured by log4j2.xml, looked for by default in the directory JMeter is launched from. Code, including plugins, must log through SLF4J. The default root level is info and the default log file is jmeter.log.

The XML above is a minimal illustration. The manual shows enabling HTTP client diagnostics by adding the <Logger name="org.apache.http" level="debug" /> line. For a one-off run, avoid editing the file and use the command line:

In the GUI, Options → Log Viewer shows the log, and an error counter at the top right turns up when something has been logged at error level. Heavy DEBUG logging is itself load on the generator (disk I/O and CPU), so do not leave it on for a measured run.

Source: Getting Started: Logging (User Manual)

If the load generator reaches the system under test through a corporate proxy, tell JMeter on the command line. These options apply to the whole JMeter process:

Use placeholders as above; a real password on the command line is visible to other users of the machine. The properties reference lists http.proxyUser, http.proxyPass and http.proxyDomain (for NTLM) for the HTTP sampler’s proxy authentication. Per-request proxy settings can also be set on each HTTP Request sampler, and then override these global ones. The proxy used by the recorder is a different thing and is covered on the recording page. Aim the Bookshelf API at localhost, which needs no proxy and is excluded with -N localhost.

Source: Getting Started: Proxy Server (User Manual)

The Apache JMeter project publishes no official Docker image and the official documentation describes only CLI mode for automation. Community images exist, for example justb4/jmeter and alpine/jmeter; they are third-party, and their JMeter and Java versions should be checked before use. The alternative is a small Dockerfile of your own that unpacks the official binary, which makes the version explicit and lets you add the JDBC drivers and plugins your plans need.

The Dockerfile is an illustration rather than an official artefact: it takes the checksum from the same archive host (a weaker check than the PGP verification described above, which you can add), and the base image and archive URL should be confirmed against the download page. Pass -Jname=value arguments to the container the same way as to the local script, and set JVM_ARGS with -e to adjust the heap. Mount the test directory so that the log, the results and the CSV data live outside the container. Containers started on a Linux host with --network host or on the Compose network can reach the Bookshelf API; from inside a container localhost is the container itself, not the host. Distributed runs in containers and CI are covered in the later pages on distributed testing and CI/CD.

Source: Getting Started: Running JMeter (User Manual), Download Apache JMeter

In distributed testing the controller and every server run the whole plan, so they must run the same JMeter version and the same Java version; data files such as CSV inputs are not sent and must exist on each node. The same discipline applies to your own workstation, the CI agent and the load generators:

Check what a machine has:

Source: Remote Testing (User Manual), Best Practices

Source: Getting Started (User Manual), Changes History