Running JMeter Using Local Command Line

The JMeter GUI is ideal for building test plans, but once they’re ready, the command line becomes the better way to run them in automated workflows.

That’s why most teams switch to non-GUI execution. It uses fewer system resources and fits naturally into CI/CD pipelines, scheduled jobs, and remote servers. You can also generate result files and HTML reports automatically after every test run.

This guide walks you through running JMeter from the command line, explains the most useful command-line options, shows you how to generate reports, covers common issues, and shares a few practical tips for making your performance testing workflow more efficient.

3 Modes to Launch the Apache JMeter

Apache JMeter can be launched in three different modes, depending on your testing needs and environment:

• GUI Mode: This is the default mode, where JMeter opens with a graphical user interface. It is useful for creating, editing, and debugging test plans. However, due to the overhead of the graphical interface, it is not recommended for running large-scale or resource-intensive tests.

• Command Line Mode (Non-GUI Mode): In this mode, JMeter runs from the terminal or command prompt without a graphical interface. It is more efficient for running tests, especially for performance testing or automated testing with large loads, as it reduces system resource consumption.

• Server Mode (Non-GUI Mode): Server mode is used for distributed testing. Here, one machine acts as the master (client) and others act as slaves (remote servers) to simulate a higher number of virtual users. It helps scale tests across multiple machines, allowing for more extensive load testing.

Why Most Teams Prefer Non-GUI Execution

If you’re only building or debugging a test plan, the JMeter GUI is perfectly fine. But when it’s time to run performance tests, the command line is usually the better option. Let’s see how:

• Lower resource usage: Without the graphical interface running in the background, JMeter can dedicate more system resources to generating load instead of rendering the UI. This becomes especially important for large or long-running tests.

• More realistic performance results: The GUI itself consumes CPU and memory, which can influence your test environment. Running in non-GUI mode removes that overhead and gives you results that better reflect your application’s actual performance.
• Easy to automate: Command-line execution works well with CI/CD pipelines, shell scripts, and scheduled jobs, making it much easier to run performance tests as part of your release process.

• Runs almost anywhere: Since it doesn’t need a desktop interface, you can execute JMeter on remote servers, virtual machines, containers, or other headless environments without any extra setup.
• Built for larger test runs: If you need to simulate thousands of virtual users, command-line mode supports distributed testing across multiple machines. That makes it much easier to scale your load tests as your application grows.

Running Your First JMeter Test from the Command Line

Once your test plan is ready, running it from the command line only takes a single command. Before you begin, make sure Java and Apache JMeter are installed and that both are available from your system’s PATH.

Open Command Prompt on Windows or Terminal on macOS and navigate to your JMeter installation or project directory.

Windows

jmeter -n -t "C:\path\to\testplan.jmx" -l "C:\path\to\results.jtl" -e -o "C:\path\to\output-folder"

macOS

jmeter -n -t /Users/yourname/path/to/testplan.jmx -l /Users/yourname/path/to/results.jtl -e -o /Users/yourname/path/to/output-folder

When the command finishes, JMeter executes the test plan, saves the raw results as a .jtl file, and generates an HTML dashboard in the output folder you specified. The dashboard includes useful metrics such as response times, throughput, error rates, and other performance statistics that help you understand how your application performed during the test.

Understanding the command:

Advanced Methods for JMeter Command Line Execution

Server (Non-GUI) mode in Apache JMeter enables performance testing at scale by distributing test execution across multiple machines. This allows you to simulate high loads efficiently. Below are three advanced methods for JMeter command line execution that work well in non-GUI mode and are suitable for CI/CD and large-scale testing environments.

1. Execute JMeter Tests with Apache Ant

Apache Ant is a Java-based build tool for automating tasks such as compiling code, packaging files, and running test scripts. It can also trigger JMeter test plans in a structured and repeatable way.

Here are step-by-step instructions to use Apache Ant to execute JMeter tests:

1. Install Apache Ant on your System

Download Ant from the official site. Unzip the package and set the environment variables:

• For Windows:

set ANT_HOME=C:\path\to\apache-ant

set PATH=%ANT_HOME%\bin;%PATH%

• For Mac:

export ANT_HOME=/path/to/apache-ant

export PATH=$ANT_HOME/bin:$PATH

• Verify the installation by running:

ant -version

This will return the Ant version number.

2. Create a JMeter Test Plan

Save your .jmx test plan (e.g., testplan.jmx) in the working directory. If you’re new to JMeter test plans, they can be created using the JMeter GUI or manually by writing the XML configuration.

3. Set Up Ant Build File

Create a file named build.xml in the same directory with the following content:

<project name="JMeterTest" default="run" basedir=".">

    <property name="jmeter.home" location="/path/to/jmeter" />

    <property name="test.plan" location="testplan.jmx" />

    <property name="result.file" location="results.jtl" />



    <target name="run">

        <exec executable="${jmeter.home}/bin/jmeter">

            <arg value="-n"/>

            <arg value="-t"/>

            <arg value="${test.plan}"/>

            <arg value="-l"/>

            <arg value="${result.file}"/>

        </exec>

    </target>

</project>

Replace /path/to/jmeter with your actual JMeter installation path.

Explanation of the Ant Build File:

• <property name=”jmeter.home” location=”/path/to/jmeter” />: Defines the path to your JMeter installation. This is a placeholder to keep paths organized.
• <property name=”test.plan” location=”testplan.jmx” />: Points to the .jmx test plan file to be executed.
• <property name=”result.file” location=”results.jtl” />: Specifies the location where the results will be stored in a .jtl file.
• <exec executable=”${jmeter.home}/bin/jmeter”>: Executes the JMeter command. The command inside <exec> will run JMeter in non-GUI mode.
• <arg value=”-n”/>: Runs JMeter in Non-GUI mode.
• <arg value=”-t”/>: Specifies the path to the .jmx file to be executed.
• <arg value=”-l”/>: Tells JMeter to save the results in a file.

4. Run the Test Using Ant

In the terminal or command prompt, run:

ant

This will execute the test in non-GUI mode using the .jmx file and generate results in a .jtl file.

5. Expected Output

Terminal output will show something like:

6. Common Issues

Here are common issues you might encounter while executing the test, along with tips for troubleshooting:

• Java or Ant Not Found: If Ant or Java is not found, double-check that the environment variables (ANT_HOME and JAVA_HOME) are set correctly and that their paths are included in your PATH.
• File Path Issues: Make sure the paths to the JMeter binary and .jmx test plan are correct in the build.xml file. If your test plan file is in a different directory, adjust the <property name=”test.plan” location=”testplan.jmx” /> line to point to the correct path.
• Out-of-Memory Issues: JMeter tests can consume a lot of memory, especially when simulating many users. If you encounter out-of-memory errors, you can increase the heap size by editing the jmeter.bat (Windows) or jmeter.sh (Mac/Linux) file in the bin/ folder and adjusting the HEAP variable.

2. Use Apache Maven to Execute JMeter Tests

Apache Maven is a powerful build automation tool used primarily for Java projects. With the help of the JMeter Maven Plugin, you can easily run JMeter tests as part of your build lifecycle, which makes it useful for automation and integration in CI/CD pipelines.

Here are step-by-step instructions to use Apache Maven to execute JMeter tests:

1. Install Apache Maven

Download Maven from the official site. Unzip the archive and set up the environment variables.

• For Windows:

set MAVEN_HOME=C:\path\to\apache-maven

Set PATH=%MAVEN_HOME%\bin;%PATH%

• For Mac:

export MAVEN_HOME=/path/to/apache-maven

export PATH=$MAVEN_HOME/bin:$PATH

Verify the installation by running:

mvn -version

This will return the version number.

2. Create a Maven Project Folder Structure with JMeter Plugin

Create a folder for your Maven project (e.g., jmeter-maven-test), and navigate to it. This folder will hold the necessary project structure.

The structure should look like this:

• pom.xml: Maven configuration file.
• src/test/jmeter/testplan.jmx: JMeter test plan file.

Place your .jmx test plan (e.g., testplan.jmx) under the src/test/jmeter/ directory. For this tutorial, the .jmx file name is testplan.jmx

3. Configure the Maven pom.xml File

Create and edit the pom.xml file and paste the following code:

<project xmlns="http://maven.apache.org/POM/4.0.0"

         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0

                             http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>



    <groupId>com.example</groupId>

    <artifactId>jmeter-test</artifactId>

    <version>1.0-SNAPSHOT</version>



    <build>

        <plugins>

            <plugin>

                <groupId>com.lazerycode.jmeter</groupId>

                <artifactId>jmeter-maven-plugin</artifactId>

                <version>3.4.0</version>

                <executions>

                    <!-- Step 1: Configure JMeter plugin -->

                    <execution>

                        <id>configuration</id>

                        <goals>

                            <goal>configure</goal>

                        </goals>

                    </execution>



                    <!-- Step 2: Run JMeter tests -->

                    <execution>

                        <id>jmeter-tests</id>

                        <goals>

                            <goal>jmeter</goal>

                        </goals>

                    </execution>

                </executions>

            </plugin>

        </plugins>

    </build>

</project>

This configuration ensures that Maven uses the JMeter Maven Plugin to run the JMeter tests.

• The <goal>configure</goal> goal prepares the environment.
• The <goal>jmeter</goal> goal executes the JMeter test plan.

4. Run the Test Using Maven

In your terminal, navigate to the project directory and execute the following command:

mvn verify

This command compiles the project and runs your JMeter test plan using the plugin.

After the command runs, Maven generates test results and saves them in the target/jmeter/ directory. This will include the result files in formats such as .jtl and the generated reports.

The reports and results, including information such as throughput, response time, and errors, will be in the target/jmeter/directory. Here’s how the output will look.

3. Run a JMeter Test from Java Code

You can also run JMeter test plans programmatically using Java code. This is useful if you want to integrate performance tests into a custom framework, run dynamic test plans, or trigger tests from within other applications.

Here are the steps to run a JMeter test from Java code:

1. Create Folder Structure

To begin running a JMeter test from Java code, you first need to set up a proper project structure. This ensures that JMeter dependencies and your test plans are neatly organized, making it easier to maintain and run tests programmatically.

Here’s how the folder structure should look:

2. Create and Save the pom.xml File:

Create a file named pom.xml in the root directory (jmeter-java-test/). Open it in a text editor and paste the following Maven configuration:

<project xmlns="http://maven.apache.org/POM/4.0.0"

         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 

         http://maven.apache.org/xsd/maven-4.0.0.xsd">



    <modelVersion>4.0.0</modelVersion>



    <groupId>com.example</groupId>

    <artifactId>jmeter-java-test</artifactId>

    <version>1.0-SNAPSHOT</version>



    <dependencies>

        <dependency>

            <groupId>org.apache.jmeter</groupId>

            <artifactId>ApacheJMeter_core</artifactId>

            <version>5.6.3</version>

        </dependency>

        <dependency>

            <groupId>org.apache.jmeter</groupId>

            <artifactId>ApacheJMeter_components</artifactId>

            <version>5.6.3</version>

        </dependency>

        <dependency>

            <groupId>org.apache.jmeter</groupId>

            <artifactId>ApacheJMeter_functions</artifactId>

            <version>5.6.3</version>

        </dependency>

    </dependencies>



    <build>

        <plugins>

            <plugin>

                <groupId>org.codehaus.mojo</groupId>

                <artifactId>exec-maven-plugin</artifactId>

                <version>3.1.0</version>

                <configuration>

                    <mainClass>com.example.JMeterRunner</mainClass>

                </configuration>

            </plugin>

        </plugins>

    </build>

</project>

This configuration defines the necessary JMeter dependencies and sets up the exec-maven-plugin to run the JMeterRunner Java class.

3. Create the Java Code (JMeterRunner.java):

Inside the src/main/java/com/example/ folder, create the file JMeterRunner.java and add the following code to run the JMeter test:

package com.example;



import org.apache.jmeter.engine.StandardJMeterEngine;

import org.apache.jmeter.save.SaveService;

import org.apache.jmeter.util.JMeterUtils;

import org.apache.jorphan.collections.HashTree;



import java.io.File;



public class JMeterRunner {

    public static void main(String[] args) {

        // Set JMeter home

        String jmeterHome = "<JMeter Path Here>";  // Update this path



        // Set JMeter properties and initialize

        JMeterUtils.setJMeterHome(jmeterHome);

        JMeterUtils.loadJMeterProperties(jmeterHome + "/bin/jmeter.properties");

        JMeterUtils.initLocale();



        // Load the JMeter test plan (JMX file)

        File jmxFile = new File("test/jmeter/testplan.jmx");  // Update path if needed

        try {

            HashTree testPlanTree = SaveService.loadTree(jmxFile);



            // Set up the engine to run the test plan

            StandardJMeterEngine jmeter = new StandardJMeterEngine();

            jmeter.configure(testPlanTree);

            jmeter.run();

        } catch (Exception e) {

            e.printStackTrace();

        }

    }

}

Update the jmeterHome path and testplan.jmx path according to your system.

4. Build and Run the Test Using Maven:

After creating the folder structure, pom.xml, and Java code, you can compile and run the test using Maven.

• Open a terminal or command prompt.
• Navigate to the root directory of your project (jmeter-java-test/).
• Run the following command to compile the project:

mvn compile

• Once the project is compiled, run the Java code with:

mvn exec:java

Maven will automatically download the dependencies (like JMeter libraries) and execute the JMeterRunner.java class to run the JMeter test plan (testplan.jmx).

After a successful run, the output in the terminal will indicate the success of the test execution. You should also see generated result files, such as .jtl files or any logs based on your test plan.

Conclusion

Running JMeter from the command line is the preferred way to execute performance tests once your test plan is ready. It uses fewer system resources than the GUI, works well with automation pipelines, and makes it easier to generate reports and analyse results after every test run.

As your testing needs grow, command-line execution also gives you the flexibility to schedule tests, run them on remote servers, and scale them across multiple machines. Combined with a well-designed test plan, it helps you build a performance testing workflow that’s faster, more repeatable, and easier to maintain.