How to clean and rename excel column headers in bulk
- Step 1Open the tool and drop your spreadsheet — Land on /excel-tools/excel-header-sanitizer (it redirects to the Header Rename tool) and drop an
.xlsx,.xls,.ods,.csv,.tsv, or.txtfile. The first row is read as the header row and each name is listed for editing. - Step 2Review the detected headers — Every header from row 1 appears with its original name on the left and an empty input on the right. Names are shown trimmed, so
First Namedisplays asFirst Name. An empty header cell shows asCol Nso you can still target it. - Step 3Type the clean replacement for each header you want to change — Enter the target name —
First Name→first_name,Order #→order_id,Date (UTC)→date_utc. Leave a field blank to keep the original header exactly as-is. The button shows a live count of how many headers you have changed. - Step 4Run the rename — Click
Rename N headers. The tool rewrites only row 1; every data row below is copied through verbatim. A summary shows headers-renamed and data-row count. - Step 5Check the preview — The result panel shows the first 10 rows with the new header row on top. Confirm your renames landed on the right columns and that no two headers accidentally collapsed to the same name.
- Step 6Download the renamed file — An
.xlsx/.xls/.odsupload downloads asname.renamed.xlsx; a CSV/TSV/TXT upload downloads asname.renamed.csv. Feed it straight into your schema-import step.
What the tool changes and what it leaves alone
The Header Rename tool operates only on row 1. Everything else is pass-through. There is no automatic case conversion, deduplication, or validation step.
| Behaviour | What actually happens | Why it matters |
|---|---|---|
| Header source | Row 1 of the first sheet is treated as headers; names are trimmed for display | A trailing space (First Name ) shows trimmed, so you rename a clean string |
| Rename model | Each header maps by column index to the new name you type; blank = keep original | Renaming is positional — moving a column elsewhere does not break the rename, but the index is what is stored |
| Auto case conversion | None. No snake_case / camelCase / PascalCase / kebab-case button exists — you type each target name | You control the exact identifier; nothing is guessed or transliterated for you |
| Collision handling | No check. If you rename two columns to the same name, the file gets two identical headers | Verify in the preview — duplicate headers break pandas, SQL COPY, and most importers |
| Data rows | Copied through unchanged — no trimming, casing, or substitution touches cell values | Zero risk of a value being rewritten (unlike cell-level Find & Replace) |
| Multi-sheet workbooks | Only the first sheet is read and written; other sheets are dropped from the output | Split a multi-tab workbook first if you need every sheet preserved |
Input formats and output naming
Accepted upload types and the exact download filename for each. XLSX-family inputs round-trip through a CSV intermediate.
| Input file | How it is read | Output filename | Format caveat |
|---|---|---|---|
.xlsx / .xls / .ods | First sheet converted to CSV in-browser (SheetJS sheet_to_csv) | name.renamed.xlsx | Output is a fresh single Sheet1 rebuilt from CSV — formulas, number formats, and styling are flattened to plain values |
.csv | Parsed with PapaParse | name.renamed.csv | Quoting and encoding preserved by the CSV writer |
.tsv / .txt | Parsed as delimited text | name.renamed.csv | Output is comma-delimited CSV regardless of the input delimiter |
Tier and size limits
Header Rename is a Pro-gated tool. The Excel hub card advertises the Excel family limits; at runtime the tool enforces the CSV family limits. Real numbers from lib/tier-limits.ts.
| Tier | Max file size | Max rows | Access |
|---|---|---|---|
| Free | 2 MB (CSV family at runtime) | 500 rows | Header Rename requires Pro — free users hit the upgrade wall |
| Pro | 100 MB | 100,000 rows | Full access; up to 5 files in batch contexts |
| Excel hub advertised | 5 MB free / 50 MB Pro | 10,000 free / 100,000 Pro | Shown on the /excel-tools card; the tool itself uses the CSV-family numbers above |
Cookbook
Real header-cleanup patterns. The left side is the raw export; the right side is what you type and what downloads.
Trailing-space and punctuation headers
The classic schema-prep set: a trailing space hidden after First Name, a # in Order #, and a parenthetical unit in Date (UTC). You type clean identifiers; data rows are untouched.
Detected headers (shown trimmed): First Name → [ first_name ] Order # → [ order_id ] Date (UTC) → [ date_utc ] Amount → [ ] (blank = keep 'Amount') Output header row: first_name,order_id,date_utc,Amount Data rows below are copied through byte-for-byte.
Keeping most headers, renaming a few
You rarely need to rename everything. Leave a field blank and the original header is kept exactly. The run button counts only the fields you actually changed.
Headers: id | Customer Name | e-mail | created at You type: (blank) | customer_name | email | (blank) Button reads: 'Rename 2 headers' Output header row: id,customer_name,email,created at
Watch out: accidental collision
There is no collision check. If you rename two columns to the same identifier, you get two identical headers — which most importers reject or silently mangle. The preview is your safety net.
Headers: Email | Email Address You type: email | email ← both renamed to 'email' Output header row (no warning): email,email Fix: give the second a distinct name (email_secondary).
XLSX in, XLSX out (formatting flattened)
Upload an .xlsx, get an .xlsx back. Because the tool round-trips through CSV, the output is a clean single-sheet workbook of plain values — any formulas, number formats, or cell styling in the original are not carried over.
Input: quarterly_report.xlsx (3 sheets, formatted, formulas) Rename: Q1 Sales -> q1_sales, Q2 Sales -> q2_sales Download: quarterly_report.renamed.xlsx - Only Sheet1 (the first sheet) is present - Cells hold computed values, not formulas - Number formats / fills are not preserved
Empty header cells
If a column has no header text in row 1, it is listed as Col N so you can still name it. This is common in exports where a key column was left unlabelled.
Headers: id | (empty) | total Displayed: id | Col 2 | total You type: (blank) | line_item | (blank) Output header row: id,line_item,total
Edge cases and what actually happens
Two columns renamed to the same name
No collision checkThe tool maps each column index to the name you type with no uniqueness check. Renaming both Email and Email Address to email produces two identical headers in the output with no warning. Most importers (pandas, PostgreSQL COPY, BigQuery) then either reject the file or silently keep only one column. Always scan the preview header row for duplicates before downloading.
Workbook has multiple sheets
First sheet onlyOnly the first sheet of an .xlsx/.xls/.ods is read (SheetNames[0]) and the download contains a single Sheet1. Other tabs are dropped. If you need every sheet renamed, process each sheet separately, or split the workbook first. The tool does not merge or iterate sheets.
Formulas and formatting in the source XLSX
Flattened by designXLSX input is converted to CSV in-browser, then the renamed CSV is written back to a brand-new XLSX. Formulas become their last computed values, and number formats, fills, fonts, and merged cells are not preserved. If you need the original formatting intact, rename headers in Excel directly — this tool is for producing a clean, import-ready values-only file.
Header text spans two rows
MisreadSome exports put a title in row 1 and the real headers in row 2. The tool always treats row 1 as headers, so a two-row or banner header is misread. Delete the banner row in your source before uploading, or the rename targets will be the wrong strings.
Header with a trailing or leading space
Trimmed for displayHeaders are trimmed when listed, so First Name shows as First Name and the replacement you type is a clean string. The original whitespace does not survive into the output header because you are supplying the new value. This is helpful for schema prep where a trailing space would break an exact-match column lookup downstream.
You leave every field blank and run
BlockedThe run button stays disabled until at least one header is changed — it reads Edit any header to rename when no field has a value. There is no no-op pass that re-emits the file unchanged; rename at least one header (or use a sibling tool if you only need a format conversion).
Free-tier user opens the tool
Pro requiredHeader Rename is Pro-gated (minTier: pro). Free accounts can open the page but hit the upgrade wall before running. The Excel hub card advertises the Excel free limit (5 MB / 10,000 rows), but the rename action itself requires Pro and enforces CSV-family limits (2 MB free / 100 MB Pro) when run.
Header that starts with a digit
PreservedThe tool stores whatever you type as the new header — including 2024_revenue. It does not validate identifiers, so a name starting with a digit is written as-is. That is fine for a CSV column label but illegal as a Python attribute or unquoted SQL identifier; type a safe form like revenue_2024 if the downstream consumer needs it.
Reserved word or special character in the new name
No validationThere is no reserved-word or character filter. If you type select or order by as a header, it is written verbatim. For database targets, prefer non-reserved snake_case; the tool will not stop you or quote the name for you. See the PostgreSQL import guide for safe-identifier rules.
Frequently asked questions
Does this tool auto-convert headers to snake_case?
No. There is no snake_case, camelCase, PascalCase, or kebab-case button. You type the exact new name for each header yourself. This is deliberate — only you know whether Order # should become order_id or order_number — and it takes well under a minute for a typical spreadsheet.
Will renaming a header change any of my data?
No. Only row 1 (the header row) is rewritten. Every data row below is copied through byte-for-byte — no trimming, casing, or substitution touches cell values. This is the core advantage over cell-level Find & Replace, which can accidentally rewrite values that happen to match a header string.
What file types can I upload?
.xlsx, .xls, .ods, .csv, .tsv, and .txt. Excel-family files are read first-sheet-only and converted to CSV in your browser; CSV/TSV/TXT are parsed directly. The same inline rename editor appears regardless of input type.
If I upload XLSX, do I get XLSX back?
Yes. An .xlsx/.xls/.ods upload downloads as name.renamed.xlsx. A CSV/TSV/TXT upload downloads as name.renamed.csv. Note the XLSX output is rebuilt from a CSV intermediate, so formulas and formatting are flattened to plain values.
Does it rename headers on all sheets in a workbook?
No — only the first sheet is read and written. Other sheets are not included in the output. If you have a multi-tab workbook, process each sheet as a separate file, or split the workbook before uploading.
What happens if I rename two columns to the same name?
The tool writes both — there is no collision check, so you get two identical headers and no warning. Most importers reject or silently drop duplicate-header files. Always check the preview header row and give colliding columns distinct names.
Will renaming break formulas that reference cells?
Formulas using cell addresses (A2, B2) are positional and would be unaffected by a header text change. But note: when you upload an XLSX, the tool flattens formulas to their computed values during the CSV round-trip anyway, so the output contains values, not live formulas.
Why is the run button disabled?
It stays disabled until you change at least one header — it reads Edit any header to rename when nothing is edited, then switches to Rename N headers once you type a value. There is no pass-through mode that re-emits an unchanged file.
How are headers with trailing spaces handled?
They are shown trimmed (First Name displays as First Name), and the replacement you type becomes the clean header. So even if you keep the same visible name, the trailing space is gone in the output — useful when an invisible space was breaking a downstream exact-match lookup.
Is my spreadsheet uploaded anywhere?
No. Parsing and renaming run entirely in your browser via SheetJS and PapaParse. Column names and all data rows stay on your device. Only an anonymous run counter (no content) is recorded for signed-in dashboard stats.
How large a file can I process?
The tool is Pro-gated. Pro allows up to 100 MB / 100,000 rows (CSV family). The Excel hub card advertises the Excel free tier (5 MB / 10,000 rows), but the rename action requires Pro. For very large files, split with a sibling tool first.
Can I run this as an automated step?
Yes. GET /api/v1/tools/csv-header-rename returns the option schema; pair the @jadapps/runner and POST a payload whose renames is a JSON map keyed by old header name or column index, e.g. {"email":"Email Address","0":"id"}. Execution is runner-backed and local — your file never reaches JAD servers. For other header normalisation, see the whitespace trimmer, case converter, and special-character stripper.
Privacy first
Every JAD Excel tool runs entirely in your browser using SheetJS and ExcelJS. Your spreadsheets, formulas, and data never leave your device — verified by zero outbound network requests during processing.