To use User Defined Variables in Apache JMeter, right click the Test Plan or a Thread Group, choose Add > Config Element > User Defined Variables, add a name and a value (for example host = www.example.com), and write ${host} wherever you need the value: the server name, path, body data, headers or a sampler’s name. JMeter replaces it before the request is sent. Steps checked against JMeter 5.6.3.
Key takeaways
- User Defined Variables keep environment values (host, port, base path) in one place instead of scattered across samplers.
- Every User Defined Variables element in the plan is processed once, at the start, wherever it sits. Use them for constants, not per-iteration data.
- Wrap values in
${__P(name,default)}to override them from the command line with-Jname=value. - For values that change per virtual user or per iteration, use a CSV Data Set Config, User Parameters or a random or counter element instead.
How to add User Defined Variables in JMeter
Add a User Defined Variables config element, type a name and a value in its table, then reference the name as ${name} in any field. The example below puts the host name of an HTTP Request in a variable, so pointing the test at another environment takes one edit.
- Open JMeter (here is how to install JMeter on Mac) and add a Thread Group: right click Test Plan, then Add > Threads (Users) > Thread Group.
- Right click the Thread Group and choose Add > Sampler > HTTP Request.
- Right click the Thread Group and choose Add > Config Element > User Defined Variables.
- Click Add and create a variable named
var1with the valuewww.example.com.
- In the HTTP Request, type
${var1}in Server Name or IP.
- Add a View Results Tree listener (Add > Listener > View Results Tree) to see what was sent.
- Run the test. In the Request tab of View Results Tree,
${var1}has been replaced withwww.example.com.
- Put
${var1}in the HTTP Request’s name as well, for exampleHTTP Request ${var1}. The results tree now labels the sample with the variable’s value, which makes results from different environments easy to tell apart.
The screenshots come from an older JMeter release (they still show the WorkBench, which JMeter 4.0 removed); the menus and fields are the same in 5.6.3.
The Test Plan element has its own User Defined Variables table, which works the same way. Many plans keep environment settings there and use separate config elements only for groups of related values.
How to use a JMeter variable in the path, body data and headers
Use the same ${name} syntax in any text field of a test element. In an HTTP Request that includes the path (/api/${version}/users), parameters, and the Body Data tab, for example {"customer": "${customerId}"}. It also works in an HTTP Header Manager value, such as Bearer ${token}, and in assertions. Variable names are case-sensitive, and an undefined name is left in the request as the literal text ${name}, which is the quickest way to spot a typo in View Results Tree.
How to override User Defined Variables from the command line
Set the value of a User Defined Variable to a property function with a default, then pass the property with -J. JMeter properties come from the command line or the properties files, so the same .jmx can run against staging and production without edits.
Name: host Value: ${__P(host,www.example.com)}
Name: threads Value: ${__P(threads,10)}jmeter -n -t plan.jmx -l results.csv -Jhost=staging.example.com -Jthreads=50Without -Jhost, the test uses www.example.com. You can also reference ${__P(threads,10)} directly in the Thread Group’s Number of Threads field. For a distributed test, -G sends a property to the remote servers too. More on running from the command line: how to start JMeter in non-GUI mode.
How User Defined Variables are processed: scope and order
The rules come straight from the JMeter component reference, and most surprises with User Defined Variables come from one of them.
- All of them run at the start. Every User Defined Variables element in the plan is processed when the test starts, no matter where it is placed. A UDV under the second Thread Group is already set before the first one runs. For simplicity, put them under the Test Plan or at the top of a Thread Group.
- Top to bottom. They are processed in the order they appear in the plan, so you can reference variables defined in an earlier UDV element or on the Test Plan.
- Not within the same element. A variable cannot use another variable defined in the same User Defined Variables table, because the values only exist once the element has been processed.
- Shared between Thread Groups. With more than one Thread Group, use different names for different values. Two UDVs that both define
hostoverwrite each other. - Copied to each thread. After processing, each thread gets its own copy. If a Regular Expression Extractor or User Parameters later sets a variable with the same name, that thread sees the new value; the other threads keep theirs.
- Functions run once. A function such as
${__Random(1,100)}in a UDV is evaluated a single time, so every thread and iteration gets the same number. Functions with a fixed result, such as${__P(host,localhost)}, are the right fit.
User Defined Variables vs User Parameters vs CSV Data Set Config
Pick the element by how often the value has to change. User Defined Variables hold one value for the whole test. User Parameters (a pre-processor) give each thread its own value and can be re-evaluated on every iteration. A CSV Data Set Config reads a new line from a file for each thread and iteration, which is what logins and search terms need.
| Element | Where to add it | Value changes | Typical use |
|---|---|---|---|
| User Defined Variables | Add > Config Element | Never during the run | Host, port, base path, API version |
| User Parameters | Add > Pre Processors | Per thread, optionally every iteration | A small, fixed set of per-user values |
| CSV Data Set Config | Add > Config Element | Per thread and iteration, from a file | Logins, search terms, IDs from test data |
Counter, Random Variable, ${__UUID()} | Config Element or a function | Every iteration or call | Unique or random IDs |
JMeter property (-J, ${__P()}) | Command line or user.properties | Set before the run, shared by all threads | Environment and load settings |
The CSV route is covered in how to use CSV Data Set to configure JMeter tests, and unique and random values in generating dynamic IDs in JMeter.
Running the same plan in the cloud
When the plan reads its host and load settings from variables, moving it to a bigger test is mostly a matter of uploading the .jmx. LoadFocus runs JMeter test plans from 25+ cloud regions with the CSV data files that go with them, and its browser-based load test builder has a Defined Variables option for the same purpose when you do not use a script.
Frequently Asked Questions
When should I use User Defined Variables in JMeter?
For values that stay the same for the whole run, such as a host name, a port or a base path. Keeping them in one config element, or in the Test Plan’s own table, means changing an environment is one edit rather than a hunt through every sampler.
How do I reference a JMeter variable in a request?
With the ${name} syntax, anywhere in the sampler: server name, path, parameters, body data, headers and the sampler’s own name. In a JSR223 element with Groovy, read it with vars.get("name") instead, so the script can be compiled once and cached.
Can I use User Defined Variables for per-user data?
No. They are resolved once at the start of the test, so every thread starts with the same value. For data that must differ per virtual user, such as logins, use a CSV Data Set Config. For a value per thread from a short list, User Parameters work too.
What is the difference between a JMeter variable and a property?
Variables belong to a thread: each thread has its own copy, and changing one does not affect the others. Properties are global to the JMeter process, are set from the command line or properties files, and are read with ${__P(name)} or ${__property(name)}. Use properties for settings you pass in, variables for values inside a run.
Why is my variable sent as the literal text ${name}?
JMeter did not find a variable with that name when the request was built. Check the spelling and case, check that the element defining it runs before the sampler, and remember that a User Defined Variables element cannot reference another variable defined in the same table.
Sources
- Apache JMeter component reference, User Defined Variables (processing at start, order, scope, functions,
__Pexample), read 23 October 2026. - Apache JMeter user manual, Functions and Variables (
${name}syntax,__Pand__property), read 23 October 2026. - Apache JMeter user manual, Getting Started: overriding properties (
-Jand-G), read 23 October 2026. - Apache JMeter user manual, Best Practices (variables are local to a thread, properties are shared), read 23 October 2026.
Related reading
- How To Use Apache JMeter To Load Test a Web Server
- Introduction to Apache JMeter Performance Testing
- How to Use Apache JMeter’s XPath Extractor?
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.
