skip to content

What does each flag in the JMeter command `jmeter -n -t plan.jmx -l results.jtl` do?

level: juniorimportance: must knowfreq 88%

answer

  1. Three flags carry almost the whole line
  2. One of them takes no value
  3. Two of the three name a file
  4. Their long forms appear in jmeter -?

basics

~10 s

-n runs JMeter without its GUI, -t names the .jmx test plan to load and run, and -l names the JTL file that every sample result is written to.

solid answer

~40 s

`-n` (long form `--nongui`) takes no argument and switches JMeter out of GUI mode; without it JMeter opens the Swing window instead. `-t` (`--testfile`) names the `.jmx` plan and is mandatory once `-n` is given — a `-n` run with no `-t` prints `Incorrect Usage:Non-GUI runs require a test plan` and stops. `-l` (`--logfile`) is optional: it makes JMeter build a `ResultCollector`, point it at that JTL file and add it on top of the loaded tree, so it records samples **in addition to** any listeners saved in the plan. Passing `-n` also makes the launcher set `java.awt.headless=true`, so the run needs no display. On the console you get the built-in Summariser's `summary` lines, `Created the tree successfully using plan.jmx` and `Starting standalone test @ ...`.

code

bash · 9 lines
bash
jmeter -n -t plan.jmx -l results.jtl -j nightly.log

# Creating summariser <summary>
# Created the tree successfully using plan.jmx
# Starting standalone test @ 2026 Sep 9 02:00:00 GMT+02:00 (1788912000000)
# Waiting for possible Shutdown/StopTestNow/HeapDump/ThreadDump message on port 4445
# summary +   1200 in 00:00:30 =   40.0/s Avg:   118 Min:    41 Max:  2011 Err:     0 (0.00%) Active: 50 Started: 50 Finished: 0
# Tidying up ...    @ 2026 Sep 9 02:10:00 GMT+02:00 (1788912600000)
# ... end of run

go deeper

for a junior

Be able to type the line from memory and say what each of -n, -t and -l names. Knowing that -n takes no value is half the marks.

for a middle

Explain that -l attaches an extra ResultCollector on top of the tree rather than replacing the plan's listeners, and that -n also forces headless AWT.

for a senior

Show what the run prints and what it does not: the Summariser lines, the UDP shutdown port, and the two silent-ish failures when -t is missing or unreadable.

for a principal

Own the decision that this line, not the GUI, is how load is driven in your organisation, and that its artefact paths are part of the standard rather than each engineer's habit.

## The three flags that make a load run `jmeter -n -t plan.jmx -l results.jtl` is the line the JMeter project itself prints as the recommended way to drive load, and it is three independent decisions: | Flag | Long form | Argument | What it does | |---|---|---|---| | `-n` | `--nongui` | none | Runs without the Swing window. `CLOptionDescriptor.ARGUMENT_DISALLOWED`, so `-n true` is a parse error. | | `-t` | `--testfile` | required | The `.jmx` file to load. Mandatory once `-n` is given. | | `-l` | `--logfile` | required | The JTL file every sample result is written to. Optional. | `jmeter -?` prints the whole option list; `jmeter -h` prints the usage text; `jmeter -v` prints the version banner. ## What `-n` changes besides hiding the window - The launcher scans the raw argument array before JMeter proper starts. If it sees `-n`, `-s` or `-g` and `java.awt.headless` is not already set, it sets it to `true` — so a CLI run needs no display and no X server. - `startNonGui` sets the system property `JMeter.NonGui` to `"true"`, which samplers and scripts can read to tell the two modes apart. - The GUI-mode banner (`Don't use GUI mode for load testing !`) is printed by `JMeterGuiLauncher`, so it does **not** appear on a `-n` run. - `FileServer.setBaseForScript` is called with the `-t` file, which makes the plan's own relative file names resolve against the directory holding the `.jmx`. ## What `-l` adds, and what it does not remove `-l` is not a listener switch. JMeter builds a `ResultCollector`, points it at the file you named and adds it to the top of the already-loaded tree. Everything the plan itself carries still runs: 1. Listeners saved in the `.jmx` keep writing to their own configured files. 2. The `-l` collector writes one row per sample on top of that. 3. If `-l` is omitted altogether, no collector is added at all and the run leaves no JTL. That is why the project's own "reducing resource requirements" advice is to delete or disable the GUI listeners in the plan and rely on `-l` alone. ## What the console shows A CLI run is not silent. Left at stock settings it prints, in order: - `Creating summariser <summary>` — `bin/jmeter.properties` ships `summariser.name=summary` uncommented, so the built-in Summariser is on by default in CLI mode. - `Created the tree successfully using plan.jmx` - `Starting standalone test @ <date> (<epoch millis>)` - `Waiting for possible Shutdown/StopTestNow/HeapDump/ThreadDump message on port 4445` — the UDP control listener, whose port comes from `jmeterengine.nongui.port` (default `4445`, searching upward to `jmeterengine.nongui.maxport`, default `4455`). - periodic `summary +` interval lines while the test runs, each ending with `Active:`, `Started:` and `Finished:` thread counts, then `summary =` running totals. - `Tidying up ... @ <date>` and `... end of run` at the end. ## The rest of the line Other flags in the same family, all optional: - `-j` names JMeter's own run log (default `jmeter.log`), `-i` points at a `log4j2.xml` logging configuration, `-L` overrides a log level (`-Ljmeter.engine=DEBUG`, or bare `-LDEBUG` for the root logger). - `-f` deletes existing result files and the report folder before the run starts. - `-e` plus `-o` generate the HTML dashboard when the test finishes. - `-p` and `-q` point at property files; injecting individual properties is a separate subject and is not covered here. ## The two ways this line goes wrong - `-n` with no `-t`: `startNonGui` throws, the console shows `Incorrect Usage:Non-GUI runs require a test plan` followed by the option list, and nothing is sampled. - `-t` naming a file that is not there: the run fails with `The file <abs path> doesn't exist or can't be opened`. Neither of these is a JMeter bug — they are the two mistakes that produce an empty results directory and a job that looks like it ran.

  • What happens if you pass -n but leave out -t?
    No engine is ever started. JMeter throws an IllegalUserActionException, so the console shows `Incorrect Usage:Non-GUI runs require a test plan` followed by the full option list. No JTL is written and nothing is sampled, so a job that only checks for a crash will not notice.
  • Does -l switch off the listeners already saved in the plan?
    No. The `-l` collector is added on top of the loaded tree, so every listener in the `.jmx` still runs and still writes its own file. JMeter's own best-practice page tells you to delete or disable those GUI listeners and rely on `-l` alone.
  • Is -l required in CLI mode?
    No. If `-l` is absent JMeter adds no ResultCollector at all — only the Summariser, if `summariser.name` is set. The test runs and prints console totals, but leaves no results file behind unless a listener inside the plan writes one.

Think of it as a printer job: -n says do not open the preview window, -t is the document, -l is the receipt the job leaves behind.

saying these in an interview costs you the question

  • Says -n takes a value, such as -n true
  • Thinks -l names JMeter's own run log rather than the sample results
  • Claims -t is optional once -n is given
  • Assumes a CLI run still needs a display or an X server
  • Believes -l disables the listeners saved in the plan