To start Apache JMeter in non-GUI mode, run jmeter -n -t test_plan.jmx -l results.jtl from a terminal. -n switches off the GUI, -t names the test plan and -l names the file that receives every sample result. Add -e -o report to get the HTML dashboard when the test ends. The official manual now calls this “CLI mode”; it is the same thing.
Key takeaways
- The JMeter manual is blunt: for load testing you must run in non-GUI (CLI) mode to get reliable results.
- Three flags cover a standard run:
-n,-tand-l. Add-e -ofor an HTML report and-fto overwrite old results. - Use the GUI to build and debug the plan, then close it and run the finished plan from the command line.
The JMeter non-GUI command
Open a terminal in JMeter’s bin folder (or anywhere, if jmeter is on your PATH) and run:
jmeter -n -t my_test_plan.jmx -l results.jtlOn Windows the same flags work with jmeter.bat, or you can drag a .jmx file onto jmeter-n.cmd in the bin folder. If jmeter is not found, your install has not added it to the PATH; our guide to installing JMeter on a Mac shows both the Homebrew route, which does it for you, and the archive route.
While the test runs, JMeter prints a summary line to the console every 30 seconds with the sample count, throughput, average and min/max response times and the error percentage. This summariser is on by default in non-GUI mode, so there is nothing to enable in jmeter.properties.
JMeter command line options for non-GUI runs
Run jmeter -? to print the full list for your version. These are the ones you will use most:
| Flag | Long form | What it does |
|---|---|---|
-n | --nongui | Run without the GUI |
-t <file> | --testfile | The .jmx test plan to run |
-l <file> | --logfile | The JTL (CSV or XML) file to write sample results to |
-j <file> | --jmeterlogfile | The JMeter run log (default jmeter.log) |
-e | --reportatendofloadtests | Generate the HTML report dashboard after the test |
-o <folder> | --reportoutputfolder | Where to write the dashboard; the folder must not exist or must be empty |
-f | --forceDeleteResultFile | Delete existing results and report folder before starting |
-g <file> | --reportonly | Build the dashboard from an existing results file, without running a test |
-J name=value | --jmeterproperty | Set a JMeter property for this run |
-q <file> | --addprop | Load an extra properties file |
-r | --runremote | Run on the servers listed in the remote_hosts property |
-R host1,host2 | --remotestart | Run on these remote servers (overrides remote_hosts) |
-G name=value | --globalproperty | Send a property to the remote servers |
-X | --remoteexit | Stop the remote servers when the test ends |
-H / -P | --proxyHost / --proxyPort | Proxy host and port for JMeter’s own requests |
-L category=level | --loglevel | Change log level, for example -Ljmeter.util=DEBUG |
-v | --version | Print the JMeter version |
A run behind a corporate proxy looks like this:
jmeter -n -t my_test_plan.jmx -l results.jtl -H my.proxy.server -P 8000How to generate the HTML report from the command line
Add -e and -o to the run and JMeter writes the dashboard when the test ends:
jmeter -n -t my_test_plan.jmx -l results.jtl -e -o ./reportThe most common error here is an -o folder that already has files in it; JMeter refuses to write into it. Either point -o at a new folder or add -f, which deletes the old results file and report folder first. If you already have a results file, jmeter -g results.jtl -o ./report builds the dashboard without running anything. To save results in a specific format, see saving JMeter results to CSV or XML.
Pass threads, duration and hosts as properties
Hard-coding 50 threads in the plan means editing the .jmx for every run. Instead, put ${__P(threads,10)} in the Thread Group’s “Number of Threads” field and pass the value on the command line:
jmeter -n -t my_test_plan.jmx -l results.jtl -Jthreads=200 -Jhost=staging.example.com__P reads the property and falls back to the default (here 10) when you do not pass it. The same plan then serves a smoke test on your laptop and a full run in CI.
Run a distributed test from the command line
With JMeter servers started on other machines, -r runs the plan on every host in remote_hosts, and -R takes an explicit list:
jmeter -n -t my_test_plan.jmx -l results.jtl -R 10.0.0.11,10.0.0.12 -X-X shuts the servers down when the test finishes, and -G sends properties to them, since -J only reaches the local controller. Our walkthrough of a JMeter distributed test in the cloud covers setting the servers up.
How to stop a JMeter test running in non-GUI mode
The bin folder has two scripts for this, .sh on macOS and Linux and .cmd on Windows:
shutdown.sh/shutdown.cmdstops the test gracefully: threads finish their current sample first.stoptest.sh/stoptest.cmdstops it abruptly.
Both send a message to the running test on UDP port 4445 (the jmeterengine.nongui.port property). JMeter only accepts that command from the same machine, so run the script on the host where the test is running.
Tips for running JMeter in non-GUI mode
- Disable debugging listeners. JMeter’s best practices say not to use View Results Tree or View Results in Table during a load test. With
-lwriting every result to a file, you can disable most listeners. - Give it more memory for big tests. The default heap is 1 GB (
HEAP="-Xms1g -Xmx1g -XX:MaxMetaspaceSize=256m"). Raise it inbin/setenv.sh(orsetenv.baton Windows), or see how to increase heap size in JMeter. - Know your machine’s ceiling. One load generator runs out of CPU, memory or network long before it runs out of threads; our note on how many concurrent users one JMeter machine can handle explains how to find that limit.
- Validate before a long run. A five-minute smoke run with
-Jthreads=1catches broken extractors and missing CSV files before you burn an hour.
When one machine is not enough, LoadFocus runs the same .jmx in the cloud from 25+ regions, with no load generators to set up. You upload the plan and its CSV files, pick regions and read the results in the browser.
Frequently Asked Questions
What is the command to run JMeter in non-GUI mode?
jmeter -n -t test_plan.jmx -l results.jtl. -n turns off the GUI, -t is the test plan and -l is the results file. Add -e -o <empty folder> to generate the HTML dashboard at the end of the run.
Why should load tests run in non-GUI mode?
The GUI and its listeners use CPU and memory on the same machine that generates the load. Under heavy load that skews response times and caps the number of threads you can run, so you end up measuring your own machine instead of the server.
So what is the JMeter GUI for?
Building and debugging the test plan. Record or write the scenario in the GUI, check it with View Results Tree and a handful of threads, then save it and run the finished plan from the command line.
Is CLI mode the same as non-GUI mode?
Yes. The JMeter user manual renamed “non-GUI mode” to “CLI mode”; the flags and behaviour are the same, and the long option is still --nongui.
How do I see results while a non-GUI test is running?
The console prints a summary every 30 seconds by default, with throughput, response times and error percentage. For live graphs, add a Backend Listener that sends metrics to a time-series database, or run the test on a hosted platform that shows results while it runs.
Sources
- Apache JMeter user manual, Getting Started: CLI mode and the full list of command-line options, read 23 October 2026.
- Apache JMeter user manual, Generating the report dashboard, read 23 October 2026.
- Apache JMeter user manual, Best practices: reducing resource requirements, read 23 October 2026.
- Apache JMeter user manual, Functions:
__P, read 23 October 2026. - Apache JMeter
bin/jmeter.properties(summariser defaults,jmeterengine.nongui.port) andJMeter.java(shutdown commands accepted only from the local host), apache/jmeter source on GitHub, read 23 October 2026.
Related reading
- How to Increase Heap Size in JMeter?
- Create an Alias to Start JMeter Locally
- How To Use Apache JMeter To Load Test a Web Server
Run this JMX in the cloud, from 25+ regions
Upload your JMeter script to LoadFocus and run it with thousands of virtual users from 25+ cloud locations, with no load generators to manage. Results show p95/p99 response times, throughput and errors per request, and a free tier is included.
