How to format a CSV for bulk QR code generation
Nearly every failed bulk QR job traces back to the spreadsheet rather than the generator. The file looked fine in Excel, exported without complaint, and then produced half the expected codes or a batch that all scan to the wrong place. This guide covers the format that works and the specific export settings that cause trouble.
The minimum viable file
A header row and a column of complete URLs:
url
https://example.com/page-1
https://example.com/page-2
https://example.com/page-3That is a valid file. Add a second column if you want meaningful filenames, which is almost always worth doing:
url,asset_id
https://example.com/assets/1001,A-1001
https://example.com/assets/1002,A-1002
https://example.com/assets/1003,A-1003Rule 1: keep the header row
The first line must be column names, not data. The generator reads those names and offers them in the two dropdowns. Without a header, your first URL becomes a column name — you lose that code, and the dropdown reads like nonsense.
Column names can be anything. There is no required naming convention:
url, Link, destination and
Column A all work equally well, because you pick the right
one after upload. A column called url or
link is merely pre-selected as a convenience.
Rule 2: URLs must be complete
A QR code has no context. It does not know what site it came from, so a relative path cannot resolve to anything.
| Value | Result when scanned |
|---|---|
https://example.com/page |
Opens the page. Correct. |
/page |
Treated as plain text. Nothing opens. |
example.com/page |
Depends entirely on the scanner. Many display it as text rather than offering to open it. |
www.example.com |
Same problem — no scheme, unreliable behaviour. |
Always include https://. If your spreadsheet holds bare
domains, prepend the scheme with a formula before exporting:
="https://"&A2.
Rule 3: quote URLs containing commas
This is the classic CSV trap. A comma inside a value splits it into two columns unless the value is wrapped in double quotes:
url,label
"https://maps.example.com/?q=51.5074,-0.1278",london-office
"https://example.com/search?tags=red,blue",red-blueExcel and Google Sheets add these quotes automatically when they export a cell containing a comma. The problem arises when the CSV is assembled by hand, by a script, or by an older internal system. If your batch produces codes that scan to a truncated URL, unquoted commas are the first thing to check.
Rule 4: export as UTF-8
If any value contains an accent, an em dash, a curly quote, or non-Latin
script, encoding matters. In Excel choose CSV UTF-8
(Comma delimited) rather than plain "CSV". The plain option uses
a legacy regional encoding, and Müller arrives as
Müller — which then sanitises into a filename nobody wants.
Google Sheets exports UTF-8 by default, so File → Download → Comma-separated values is safe.
Semicolons and tabs are fine
In locales where the comma is the decimal separator — much of Europe — Excel exports CSV files using semicolons instead:
url;asset_id
https://example.com/1;A-1001This works without any changes on your part. The delimiter is detected automatically, so semicolon-separated and tab-separated files are read correctly and your column names appear in the dropdowns exactly as they should. There is no need to re-export as comma-delimited or to find-and-replace anything.
Tab-separated data is handled the same way, which means a block of cells
copied straight out of a spreadsheet and saved as a
.csv file will parse correctly too.
The one thing to check is that your chosen delimiter does not also appear inside an unquoted value — the same rule as commas, above.
Rule 5: mind the trailing blank rows
Excel frequently exports empty rows below your data, particularly if cells there were ever formatted or clicked. Rows with no content are filtered out, and rows with an empty URL cell are skipped during generation — so blank rows are harmless, but they explain a common confusion:
"My CSV has 402 rows but I only got 400 codes." Two of those rows were blank, or had an empty URL. Sort by the URL column before exporting and delete anything below the last real value.
Rule 6: strip stray whitespace
A URL with a leading or trailing space is encoded with the space
included, and some scanners will refuse it. Values are trimmed when read,
which handles the common case — but whitespace inside a URL
(from a line break pasted out of an email, say) is not something any tool
can safely guess at. Run =TRIM(A2) over a suspect column
before exporting.
If a file still will not load, or loads with the wrong number of rows, fixing CSV upload problems goes through each error message in turn — along with the failures that produce no message and quietly encode the wrong thing.
What about Excel files?
.xlsx and .xls files are not supported —
upload requires .csv. Converting takes ten seconds
(Save As or Download as) and avoids a class of problems
that come with spreadsheet formats: formulas that have not been evaluated
to values, hidden sheets, merged cells, and number formatting that
displays one thing while storing another.
That last one bites people with IDs. A column of values like
0012 is often stored by Excel as the number 12 and merely
displayed with leading zeros. Export to CSV and you get
12, so your filenames lose their padding. Format the
column as Text before entering the values, or build the string with a
formula.
A worked example
Here is a file exercising most of the rules at once — quoted commas, a text-formatted ID with padding, and complete URLs:
url,room_id,floor
https://hotel.example.com/room/0101,0101,1
https://hotel.example.com/room/0102,0102,1
"https://hotel.example.com/map?pin=51.5074,-0.1278",lobby,0
https://hotel.example.com/room/0201,0201,2
Upload this, choose url as the URL column and
room_id as the filename column, and you get
qr_0101.png, qr_0102.png,
qr_lobby.png and qr_0201.png. Choosing
floor instead would produce qr_1.png,
qr_1_2.png, qr_0.png, qr_2.png —
technically fine, practically useless, which is the point made in
choosing a filename column.
Verifying before you commit
Open the exported CSV in a plain text editor — not Excel — before uploading. Excel re-interprets the file and hides exactly the problems you are looking for. A text editor shows you the literal delimiters, quotes and encoding artefacts as they actually are.
Then test with a small file first. Export ten rows, generate, and check the filenames and scan a code. Ten rows takes a minute and catches everything that a four-hundred-row run would have caught expensively.