skip to content

Headless Execution

Running a plan from the command line rather than the GUI, and keeping the machine that generates the load from quietly becoming the thing you are actually measuring.

on this pageshow

explore

questions

27

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
open as a page

Why does Apache JMeter print a banner telling you not to load test in GUI mode?

level: juniorimportance: must knowfreq 74%

basics

~20 s

JMeter prints it on every GUI launch because the GUI is for creating and debugging a plan, not for driving load. The banner also gives the command line to use instead: jmeter -n -t [jmx file] -l [results file] -e -o [report folder].

open as a page

In Apache JMeter's bin/jmeter launcher, which environment variable sets the JVM heap, and what is its default?

level: juniorimportance: must knowfreq 68%

basics

~10 s

HEAP. Apache JMeter's bin/jmeter launcher defaults it to -Xms1g -Xmx1g -XX:MaxMetaspaceSize=256m, so an injector starts with a fixed one-gigabyte heap unless HEAP is exported first, normally from bin/setenv.sh.

open as a page

Which JMeter listeners keep a copy of every sample, and which one is built for a load run?

level: juniorimportance: must knowfreq 74%

basics

~20 s

Most JMeter listeners keep every sample they receive, View Results Tree and View Results in Table included. Simple Data Writer keeps none - it writes the row and lets the result go, so load runs use it.

open as a page

In Apache JMeter, what do the -J and -D command-line flags each define?

level: juniorimportance: must knowfreq 68%

basics

~10 s

JMeter's -J flag defines a JMeter property inside the running JMeter instance; -D defines a Java system property in the JVM. Both take name=value, may be repeated, and are applied while JMeter starts up.

open as a page

A JMeter plan runs 500 threads with a View Results Tree still attached. What does that cost?

level: middleimportance: must knowfreq 64%

basics

~20 s

Each of the 500 threads calls the listener inside its own loop and queues behind one shared buffer. In GUI mode that buffer holds up to 500 whole sample results, response bodies included, redrawn twice a second.

open as a page

In a JMeter non-GUI run, what do the summariser's + and = console lines each report?

level: middleimportance: must knowfreq 62%

basics

~20 s

The + line is a delta covering only the window since the last report; the = line is the running total for the whole run so far. Only the + line carries Active, Started and Finished thread counts.

open as a page

Which JMeter CLI flag stops a nightly `-l results.jtl` run from appending to last night's rows?

level: middleimportance: should knowfreq 52%

basics

~20 s

The -f flag, long form --forceDeleteResultFile. It deletes existing results files and the web report folder before the test starts. Without it, JMeter opens an existing CSV results file in append mode and never rewrites the header.

open as a page

An Apache JMeter run is started with JVM_ARGS="-Xmx4g" and HEAP left unset. What heap does the JVM get?

level: middleimportance: should knowfreq 52%

basics

~10 s

Maximum 4 GB, initial still 1 GB. The launcher expands HEAP's default first and appends JVM_ARGS afterwards, so the later -Xmx4g wins while -Xms1g and -XX:MaxMetaspaceSize=256m stay on the line untouched.

open as a page

In JMeter, what does each extra Thread Group thread allocate before it sends a request?

level: middleimportance: should knowfreq 50%

basics

~10 s

One real platform thread, its own clone of everything under that Thread Group, and its own copy of the variables. Plan size therefore multiplies by thread count before the first request goes out.

open as a page

Why does JMeter, not the JVM, handle a -D flag typed on the jmeter command line?

level: middleimportance: should knowfreq 41%

basics

~10 s

The bin/jmeter launcher places everything you type after -jar ApacheJMeter.jar, so the JVM treats it as an application argument. JMeter's own parser matches -D and calls System.setProperty during its startup.

open as a page

What does JMeter's -p flag replace, and what does -q add on top of it?

level: middleimportance: should knowfreq 34%

basics

~10 s

JMeter's -p names the base property file to load instead of bin/jmeter.properties and may appear only once. -q names an extra property file merged on top of the current set, and may be repeated.

open as a page

Why does night two of `jmeter -n -t plan.jmx -l r.jtl -e -o report` fail before any sampling?

level: seniorimportance: should knowfreq 46%

basics

~20 s

The -o folder must not exist or must be empty. JMeter checks it before loading the plan, so the first night's dashboard files make the second night abort with 'Cannot write to ... as folder is not empty' and exit status 1.

open as a page

A JMeter injector started via bin/jmeter.sh ignores the HEAP you set. What does that script do differently?

level: seniorimportance: should knowfreq 31%

basics

~10 s

It exports JMETER_COMPLETE_ARGS=true before calling bin/jmeter, which makes that script set ARGS empty. Only JVM_ARGS and JMETER_OPTS then reach java, so HEAP, GC_ALGO and the OOM heap-dump flag are all dropped.

open as a page

Your JMeter plan ticks Retrieve All Embedded Resources on every page sampler. What does the injector pay?

level: seniorimportance: should knowfreq 46%

basics

~20 s

Every HTML response is parsed on the sampling thread, and each asset becomes another request whose result hangs off a container result JMeter builds for the page. That container can carry dozens of results, and every listener sees all of them.

open as a page

A JMeter run with -Jenv.host=prod.internal -q staging.properties still hits staging. Why?

level: seniorimportance: should knowfreq 27%

basics

~10 s

JMeter applies command-line property options in the order they appear. The -q file is read after the -J flag and copies its own env.host over the value the flag had just set.

open as a page

A JMeter run's summariser rate flattens while its Active count keeps climbing. Which JMeter output records that?

level: seniorimportance: should knowfreq 52%

basics

~20 s

Successive + delta lines hold the story: the /s figure, the Active count, the Avg time and the Err share, window by window. Beside them sit jmeter.log at ERROR and any gap where no line was printed at all.

open as a page

What happens to a JMeter non-GUI run when a sampler thread throws OutOfMemoryError?

level: seniorimportance: should knowfreq 48%

basics

~10 s

The thread dies and the run carries on. JMeter's default uncaught-exception handler logs an ERROR block in jmeter.log and prints one line to stderr, and bin/jmeter's always-on heap-dump flag leaves a .hprof file behind.

open as a page

How would you standardise the JMeter CLI line and artefact paths a team's nightly load run uses?

level: principalimportance: should knowfreq 36%

basics

~20 s

Fix one canonical invocation: absolute paths or a fixed working directory, an explicit .jmx rather than LAST, clean artefacts each run via -f or a fresh name, -e paired with -l and an empty -o folder, and the run log kept somewhere readable.

open as a page

Each JMeter injector in your team has bin/jmeter hand-edited to raise the heap. How would you get that under control?

level: principalimportance: should knowfreq 34%

basics

~10 s

Move the setting into bin/setenv.sh, which bin/jmeter sources before applying its own defaults and which an upgrade cannot overwrite. Set the whole HEAP string per machine class, and forbid edits to the shipped launcher.

open as a page

Across a team's JMeter plans, how would you decide what a load run may record and keep?

level: principalimportance: should knowfreq 38%

basics

~20 s

Set a default the injector can always afford - a lean writer, errors only, nothing retained - and make richer recording an explicit, time-boxed exception that someone owns rather than a habit plans drift into.

open as a page

One JMeter plan serves staging and production. Which values would you pass as -J flags and which in a -q file?

level: principalimportance: should knowfreq 32%

basics

~20 s

Put each environment's stable values in a reviewable -q property file per environment, and reserve -J for the few values that genuinely vary run to run. Keep credentials out of -J, whose value JMeter logs verbatim.

open as a page

Across a team's headless JMeter runs, which of JMeter's own output would you require every run to archive?

level: principalimportance: should knowfreq 38%

basics

~20 s

At minimum the captured stdout carrying the summariser lines, a per-run jmeter.log kept with -j, and the results file. JMeter tracks nothing about the injector host during a run, so decide separately where that comes from.

open as a page

What does Apache JMeter resolve the special file name `LAST` to in `-t LAST`?

level: middleimportance: nice to knowfreq 22%

basics

~20 s

The most recently opened test plan from the JMeter GUI's Open Recent list, which lives in the Java user preferences node for LoadRecentProject. On a host where that user never ran the GUI it resolves to nothing.

open as a page

In Apache JMeter's bin/jmeter, what is VERBOSE_GC and what must you do before it produces anything?

level: middleimportance: nice to knowfreq 24%

basics

~10 s

VERBOSE_GC is a slot the launcher expands into the JVM options between HEAP and GC_ALGO. Apache ships it unset, with two commented-out -Xlog:gc candidates, so you must uncomment one or export your own.

open as a page

Why can JMeter's non-GUI summariser print nothing for minutes while the test is still running?

level: middleimportance: nice to knowfreq 32%

basics

~20 s

Nothing schedules the line. JMeter checks whether a reporting boundary has passed only when a sample result arrives, so a window in which no sample completes produces no line at all rather than a zero-rate one.

open as a page

In JMeter, what does the -G flag do with an argument that contains no equals sign?

level: seniorimportance: nice to knowfreq 19%

basics

~20 s

JMeter reads the whole argument as a path to a properties file and loads every key in it into the global property set. If that path cannot be read, JMeter does nothing and logs nothing.

open as a page