How to Create an Alias to Easily Start JMeter on your Local Machine

Key takeaways

• Add one line to ~/.zshrc (macOS default shell since Catalina) or ~/.bash_profile (bash), run source on that file, and typing jmeter starts the GUI from any folder.
• With Homebrew you usually do not need an alias at all: brew install jmeter already puts a jmeter command on your PATH.
• An alias earns its place when you run an unpacked Apache archive, or keep several JMeter versions side by side.

To start JMeter from any terminal window, add an alias that points at the bin/jmeter script of your installation. Apache JMeter is a Java-based, open source tool for functional and load tests of websites, REST and SOAP APIs and other services, and its GUI is launched by that one script. The steps below work on macOS with zsh or bash.

Which shell file do I edit for a JMeter alias?

Aliases live in the startup file of your shell, and the file depends on the shell. Apple made zsh the default shell for new user accounts starting with macOS 10.15 Catalina (support.apple.com, October 2026), so on a current Mac the file is ~/.zshrc, which zsh reads for every interactive shell. If you switched back to bash, or you upgraded an old Mac that kept it, use ~/.bash_profile: Terminal opens bash as a login shell, and a login bash reads ~/.bash_profile, not ~/.bashrc. Check which one you have with echo $SHELL.

How to create the alias on a Mac

1. Install JMeter with Homebrew or download an archive (see the next section for both paths).
2. Open the shell file in an editor. nano ~/.zshrc is the easiest; the original version of this post used Vim. Do not use sudo, it can leave the file owned by root.
3. Add the alias on its own line, then save the file.
4. Load it into the window you are in with source ~/.zshrc (or source ~/.bash_profile). New terminal windows read the file by themselves.
5. Type jmeter. The GUI opens.

The shell I use is iTerm with Oh My Zsh, and Oh My Zsh keeps its configuration in the same ~/.zshrc, so the alias goes in that file too. It works the same in the stock Terminal app.

What should the alias point to?

The target is the bin/jmeter script, and it depends on how you installed JMeter.

Unpacked Apache archive. Download apache-jmeter-5.6.3.tgz from the Apache JMeter download page, unpack it (the original post used 5.4.1, the current release on that page is 5.6.3 and it needs Java 8 or newer), and point the alias at the folder you unpacked into:

alias jmeter="$HOME/Downloads/apache-jmeter-5.6.3/bin/jmeter"

Use $HOME rather than ~ inside the double quotes, because the shell does not expand a tilde there. The script has its own shebang, so the sh prefix from the first version of this post is not needed. If you would rather not leave JMeter in Downloads, move the folder somewhere permanent first and use that path.

Homebrew. The formula installs JMeter 5.6.3 and a wrapper that sets JAVA_HOME to its own OpenJDK 21 (formulae.brew.sh, October 2026). Homebrew links that wrapper into its bin folder, which is /opt/homebrew/bin on Apple Silicon and /usr/local/bin on Intel Macs, so jmeter already works without an alias. If you still want an explicit one, let Homebrew resolve the prefix for you instead of hard-coding either folder:

alias jmeter="$(brew --prefix jmeter)/bin/jmeter"

Because the double quotes run brew --prefix once when the file loads, the alias holds the resolved path. See the install JMeter on Mac guide for the whole Homebrew setup, and where Homebrew keeps the JMeter configuration files if you need to edit jmeter.properties.

Steps to add an alias from the terminal (macOS Catalina, JMeter 5.4.1 at the time of the screenshot)

Apache JMeter started using an alias from the terminal

Alias or PATH: which is better for JMeter?

An alias is a shortcut you define in the shell, and it only exists in shells that read the file. Adding the bin folder to your PATH makes the real jmeter script available to every program that searches the PATH, which is the better route for scripts and CI-style commands such as the non-GUI run. Put this line in the same startup file:

export PATH="$HOME/Downloads/apache-jmeter-5.6.3/bin:$PATH"

An alias is the simpler choice when you want a custom name, or a fixed set of options. Aliases can carry environment variables, for example a larger heap, which JMeter reads from the HEAP variable (see how to increase the JMeter heap size):

alias jmeter-big='HEAP="-Xms2g -Xmx4g" jmeter'

How do I keep several JMeter versions?

Give each version its own alias name and the right version is always the one you typed:

alias jmeter56="$HOME/tools/apache-jmeter-5.6.3/bin/jmeter"
alias jmeter54="$HOME/tools/apache-jmeter-5.4.1/bin/jmeter"

Run type jmeter to see what a name resolves to right now. It prints the alias target, or the file the shell found on the PATH.

Troubleshooting a JMeter alias

• command not found: jmeter after editing the file. The window has not read the file yet. Run source ~/.zshrc, or open a new window. Also check you edited the file of the shell you are in (echo $SHELL).
• Works in one terminal and not another. Bash and zsh read different files, so an alias written to ~/.zshrc is invisible to a bash session.
• no such file or directory on the alias target. The path is wrong or the archive moved. List it with ls first.
• An error about Java. JMeter needs Java 8 or newer on the machine. Run java -version to check, and see the install guide linked above for Java on a Mac.

If you want to run the same JMeter test plan from several world regions instead of your laptop, LoadFocus runs uploaded .jmx files from its cloud locations.

Written by Bogdan Vazzolla.

LoadFocus is a cloud testing platform for websites and APIs: it runs load tests and JMeter scripts from the cloud, monitors APIs and page speed, and explains results in plain language.

Frequently Asked Questions

Why bother with an alias for JMeter?

It saves typing the full path to the jmeter script on every launch, which adds up when you start JMeter several times a day while building a plan.

Why does my alias disappear when I open a new terminal?

It was only defined in that shell session. Put the line in ~/.zshrc (zsh) or ~/.bash_profile (bash) and every new terminal defines it for you.

Do I need an alias if I installed JMeter with Homebrew?

No. The Homebrew formula puts a jmeter command in Homebrew’s bin folder, which is already on your PATH once Homebrew is set up. An alias only helps if you want a different name or extra options.

What if I have several JMeter versions installed?

Name one alias per version, such as jmeter56 and jmeter54, each pointing at that version’s bin/jmeter. Otherwise you can lose time debugging behaviour that belongs to a different version than the one you think you started.

Sources

• Apache JMeter download page and requirements: jmeter.apache.org/download_jmeter.cgi (October 2026)
• Homebrew jmeter formula (5.6.3, openjdk@21, wrapper script): formulae.brew.sh/formula/jmeter (October 2026)
• zsh is the default shell since macOS 10.15: support.apple.com/en-us/102360 (October 2026)
• zsh startup files: zsh.sourceforge.io/Intro/intro_3.html (October 2026)

Related reading

• JMeter Load Testing Tutorial: Local, Distributed, Cloud
• How Does JMeter Work? Threads, Samplers and Results