Bulk Replace
How-to

How to Bulk Find and Replace Using a List of Words From a CSV

Keep your find and replace pairs in a spreadsheet and apply them to every file in one run. CSV layout tips, a PowerShell loop and a no-script method.

Updated 5 minute read The Bulk Replace team

To bulk find and replace from a list, put your pairs in a two-column file (the text to find in the first column, the replacement in the second), then apply every row to every file in one run. You can do that with a short PowerShell loop over a CSV, or by importing the CSV into a batch find and replace tool that runs the rows as stacked rules. Either way, the list becomes the single source of truth, so you never retype terms or miss one.

This guide covers how to build the CSV properly, two ways to apply it, and the ordering and matching rules that keep a long list from tripping over itself.

When a list beats typing replacements

  • Rebrands and renames. A product, company or feature name changes, along with a dozen related terms.
  • Glossaries. Technical writers keep approved terminology in a spreadsheet and need every doc to follow it.
  • URL and path migrations. Hundreds of old URLs map to new ones after a site restructure.
  • Data clean-ups. Codes, abbreviations or misspellings that need standardizing across many files.

In each case, someone usually already has the mapping in Excel. The goal is to use it directly.

Step 1: build the CSV

Create a spreadsheet with a header row and two columns:

FindReplace
Acme Widgets ProZenith Tools Pro
Acme WidgetsZenith Tools
support@acme-widgets.comhelp@zenith-tools.com
/products/old-page.html/tools/new-page.html

Then save it correctly:

  1. In Excel, choose File → Save As.
  2. Pick CSV UTF-8 (Comma delimited) (*.csv) as the file type. Plain "CSV (Comma delimited)" saves in the ANSI code page, which can mangle accented or non-Latin characters.
  3. Click Save and accept the warning about features that CSV cannot keep.

A few CSV details matter:

  • Commas and quotes inside values. Excel wraps those values in double quotes automatically. If you build the file by hand, do the same, and double any quote inside a value ("He said ""hi""").
  • Leading and trailing spaces. A stray space at the end of a cell becomes part of the search term and causes misses. Use Excel's TRIM() to clean the column.
  • Empty replacements. An empty Replace cell means "delete this text". Make sure that is what you intend.

Step 2: sort the list

Rows are applied in order, and each one sees the result of the rows before it. Sort so that:

  • Longer terms come before shorter terms they contain. Acme Widgets Pro must run before Acme Widgets, which must run before Acme. Otherwise the short term changes part of the long one first, and the long rule finds nothing.
  • No replacement creates text that a later row will match, unless that is deliberate.

A quick way to sort by length in Excel: add a helper column with =LEN(A2), sort the table by it from largest to smallest, then delete the helper column before saving.

Step 3a: apply the list with PowerShell

With the CSV saved as rules.csv (headers Find and Replace), this applies every row to every .md file in the folder tree:

$rules = Import-Csv rules.csv -Encoding UTF8

Get-ChildItem -Recurse -File -Filter *.md | ForEach-Object { $t = Get-Content $_.FullName -Raw -Encoding UTF8; $n = $t; foreach ($r in $rules) { $n = $n.Replace($r.Find, $r.Replace) }; if ($n -ne $t) { Set-Content $_.FullName $n -NoNewline -Encoding UTF8; $_.FullName } }

Notes on this script:

  • .Replace() is literal and case-sensitive, which is usually right for a glossary. Use -replace if your list contains regex patterns, and [regex]::Escape($r.Find) if it contains literal text with dots or brackets that you want to match case-insensitively.
  • There is no whole-word option with .Replace(). To match whole words only, use $n = $n -creplace ('\b' + [regex]::Escape($r.Find) + '\b'), $r.Replace. If a replacement could contain a $, escape it as $$.
  • Back up the folder first. The script overwrites files and has no undo.
  • In Windows PowerShell 5.1, -Encoding UTF8 writes a byte order mark. See our PowerShell replace guide for alternatives.

Step 3b: import the list into a batch tool

If you would rather not maintain a script, Bulk Replace imports whole rule sets from a CSV. The rows become stacked rules that run in order during one pass:

  1. Choose the folder, include sub-folders, and filter by extension (for example .md .html .txt).
  2. Import the CSV. Each row becomes a rule, and you can still add or edit rules by hand, or switch individual rules to whole-word, case-sensitive or regex matching.
  3. Check the before/after preview. Every file and every match is listed, with a total count. Untick any match that should keep the old wording, such as a quote or a historical note.
  4. Apply. Files are backed up first, one click undoes the whole job, and a timestamped report of files changed and match counts can be exported as CSV for review.

Save the folder, filters and rules as a Bulk Replace project so the same glossary can be applied to new files later in two clicks.

Keeping the list maintainable

A replacement list tends to grow and get reused. A few habits keep it reliable:

  • Add a notes column in your master spreadsheet explaining why each row exists, then export only the Find and Replace columns to the CSV you run.
  • Keep the list in version control or a shared folder, so everyone applies the same version.
  • Remove rows that no longer match anything after a few runs, so the list stays readable.

Checking the result

  1. Search for every old term. Any that remain point to a rule that was shadowed by an earlier one, a case difference, or a stray space in the CSV.
  2. Search for doubled results. Text like Zenith Tools Tools or Zenith Zenith shows that two rules overlapped.
  3. Spot-check a few files in full, especially those with the most matches.

Common problems

SymptomLikely causeFix
A term was not replaced anywhereA shorter row ran first, or the cell has a trailing spaceSort by length; TRIM the column
Accented terms garbledCSV saved as ANSI, or read with the wrong encodingSave as CSV UTF-8 and read it as UTF-8
Part of a longer word changedNo whole-word matchingTurn on whole word, or use \b in regex
Only some capitalizations changedCase-sensitive matchingAdd a row for each case form

For more on ordering and overlapping terms, see how to find and replace multiple words at once. If the list is a documentation glossary, our guide to updating terminology across documentation covers plurals, capitalization and code samples.

Frequently asked questions

What should a find and replace CSV look like?

Two columns: the text to find and the text to replace it with, one pair per row. Save it as CSV UTF-8 if any terms contain accented or special characters.

Can I make the CSV in Excel?

Yes. Put the find terms in column A and the replacements in column B, then use File, Save As and choose CSV UTF-8 (Comma delimited).

What if one term is part of another term in my list?

Sort the list so longer terms come first, or use whole-word matching, so a short term does not change part of a longer one before its own rule runs.

Get three guides like this every month, plus software update notices.Subscribe →