Key takeaways
- A CSV Data Set Config reads one line of a file per thread iteration and puts its columns into JMeter variables such as
${user}. - Relative filenames are resolved against the folder of the saved test plan, so a CSV next to the
.jmxcan be referenced by name alone. - Decide what happens at the end of the file: with Recycle on EOF off and Stop thread on EOF off, every variable becomes
<EOF>. - Set the sharing mode on purpose. The default, All threads, shares one file between every thread.
The CSV Data Set Config element in Apache JMeter reads lines from a file and splits them into variables, so each virtual user can send different data, such as a different username and password on every request. This post builds a small test with a Thread Group, a CSV Data Set Config, an HTTP Request and a View Results Tree, then goes through every field of the element as documented for JMeter 5.6.
How do I add a CSV Data Set Config to a JMeter test?
Open JMeter, create a new test plan and add a Thread Group.
Inside the Thread Group, add these elements (right-click the Thread Group, then Add):
- Config Element > CSV Data Set Config
- Sampler > HTTP Request
- Listener > View Results Tree
The JMeter manual says the CSV Data Set Config is easier to use than the __CSVRead() and __StringFromFile() functions, suits a large number of variables, and is a good fit for “random” and unique values: create the data before the test instead of generating it at run time, which costs CPU and memory.
What are the CSV Data Set Config fields in JMeter?
These are the fields in the order the JMeter manual lists them (component reference, JMeter 5.6, checked October 2026):
| Field | What it does |
|---|---|
| Filename | The file to read. Relative names are resolved against the path of the active test plan. |
| File encoding | The encoding to use if it is not the platform default. |
| Variable Names | The variable names, separated by the delimiter. Leave it empty to take the names from the first line of the file. |
| Ignore first line | Skips the first line of the file. Used only when Variable Names is filled in. |
| Delimiter | The character that splits each line. Write \t for a tab. |
| Allow quoted data? | Lets a value sit inside double quotes so that it can contain the delimiter. |
| Recycle on EOF? | Start again at the first line when the file ends. Default: true. |
| Stop thread on EOF? | Stop the thread at the end of the file, if Recycle is false. Default: false. |
| Sharing mode | Which threads share the file. Default: All threads. |
Filename: relative to the test plan
A relative path is resolved against the folder of the saved .jmx, so a CSV in the same folder is just file1.csv. Save the test plan before you run it, because an unsaved plan has no folder to resolve against. JMeter treats file1.csv and ./file1.csv as two different files, so use one spelling everywhere if several elements point to the same data. Absolute paths work on your own machine but usually break when the test runs elsewhere.
Variable names and the header line
Our example file holds a list of users and passwords, so the Variable Names field is user,password, separated by the same delimiter as the data:
John1,password1
John2,password2
John3,password3If your file has a header line, there are two choices. Leave Variable Names empty and JMeter reads the column names from the first line. Or fill Variable Names in and tick Ignore first line so the header is not used as data. In both cases the delimiter must be set correctly. If a line has fewer values than there are variables, the remaining variables are not updated and keep their previous value.
Delimiter and quoted data
Comma is the default choice and the simplest to read. When a value can contain a comma, such as "Smith, John", enable Allow quoted data. The manual’s example: 1,"2,3","4""5" becomes the three values 1, 2,3 and 4"5, with a doubled quote standing for one quote inside a quoted value. The manual also states that quoted values may contain new lines.
Recycle on EOF and Stop thread on EOF
These two settings decide what happens when the threads have used every line:
| Recycle on EOF | Stop thread on EOF | Result at the end of the file |
|---|---|---|
| True | (ignored) | Reading starts again at the first line. |
| False | False | Every variable is set to <EOF>, and the test keeps running. |
| False | True | The thread stops. |
The <EOF> text can be changed with the JMeter property csvdataset.eofstring. Setting Recycle to false with Stop thread false is a trap: the samplers keep running and send the literal string <EOF> as the username. For unique data such as signup emails, use Recycle false and Stop thread true, and make the file longer than the test will consume. For login accounts that can be reused, leave Recycle on.
Sharing mode
By default the file is opened once, and each thread uses a different line. Lines are read at the start of each test iteration, so the order in which lines reach threads depends on which thread runs first and can change between runs. The sharing modes are:
- All threads (default): one file, shared by every thread in the test plan.
- Current thread group: the file is opened once for each thread group that holds the element.
- Current thread: the file is opened separately for each thread, so every thread reads the whole file from the top.
- Identifier: all threads that use the same identifier share one file. Use it to share a file between two thread groups but not a third.
If every thread needs its own set of values, make one file per thread (test1.csv, test2.csv and so on), name it test${__threadNum}.csv in the Filename field and set Sharing mode to Current thread.
CSV variables are defined at the start of each test iteration, after configuration processing. That means they cannot feed elements that read their settings at configuration time, such as the JDBC Connection Configuration. They do work in the HTTP Authorization Manager.
How do I use the CSV variables in an HTTP Request?
In the HTTP Request sampler, refer to a column as ${name}. To keep the example short, we append both variables to the path of a GET request:
https://example.com?${user}&${password}
In a real test you would put them in request parameters or in a POST body. Run the test and open the View Results Tree: the request paths are filled in from the file, one line per iteration.
GET https://example.com?John1&password1
GET https://example.com?John2&password2
GET https://example.com?John3&password3
If the paths still show ${user}, the variable name does not match the Variable Names field, or the CSV Data Set Config sits outside the scope of the sampler. The element must be in the same Thread Group, or higher up in the tree.
For more on feeding test data, see using CSV data in JMeter tests, parameterization in JMeter and the older walk-through that extracts a token from a login response.
How do I run a JMeter test with a CSV file in the cloud?
When JMeter runs on several machines in its own distributed mode, the manual says the CSV file must be on each server, in the correct relative directory, and absolute paths are unlikely to work in remote mode unless the remote server has the same folder layout. Each machine reads its own copy, so run a short test first and check how rows are used before relying on unique data.
On LoadFocus, upload the .jmx and the CSV file together. The JMeter cloud load testing page says CSV data files go up with the plan and that thread groups, timers, assertions and JSR223 samplers run as they do on your machine. The page also lists 25 regions and a setting for virtual users, duration and ramp-up per run. Keep the filename relative in the plan, as above, so it does not depend on a folder on your laptop.
To save run results to a CSV rather than read data from one, see saving JMeter results to a CSV or XML file.
Written by Bogdan Vazzolla.
Frequently Asked Questions
Why use a CSV data set in JMeter?
So each virtual user works with different inputs. Sending one set of values from every thread means the server answers everything from cache, and the result describes a scenario that never happens in production.
What does the sharing mode change?
Which threads see which rows. With All threads (the default) the whole test plan shares one file. Current thread group gives each thread group its own copy, Current thread gives every thread the whole file from the first line, and Identifier shares a file between the groups that use the same name.
What happens when the CSV file runs out of lines?
It depends on two checkboxes. With Recycle on EOF on, reading starts again from the first line. With Recycle off and Stop thread on EOF on, the thread stops. With both off, all variables become <EOF> and the test keeps sending requests with that value.
Does the CSV file need a header line?
No. Fill in the Variable Names field and every line is data. If the file has a header, either leave Variable Names empty so JMeter reads the names from it, or fill the names in and tick Ignore first line.
Where do I put the CSV file?
Next to the saved .jmx file, then use the filename alone. JMeter resolves relative names against the test plan’s folder.
Can a CSV value contain a comma?
Yes, if you enable Allow quoted data and wrap the value in double quotes. Without it, the comma splits the value in two.
Sources
- Apache JMeter, Component Reference: CSV Data Set Config (JMeter 5.6, checked October 2026).
- LoadFocus, JMeter load testing (checked October 2026).
