Bulk Replace
How-to

How to Find and Replace Whole Words Only, Without Changing Parts of Words

Stop find and replace changing parts of longer words, like cat in category. Use whole-word options and regex word boundaries, and know where they fail.

Updated 5 minute read The Bulk Replace team

To find and replace whole words only, turn on your tool's Match whole word option, or in regex put \b on both sides of the word: \bcat\b. Either way, cat is replaced but category, concatenate and bobcat are left alone. Whole-word matching has blind spots, though: hyphens, dots and symbols count as boundaries, and terms that start or end with a symbol (like .NET or C++) need a different pattern. This guide covers both the simple case and the exceptions.

Why partial matches happen

A normal find and replace looks for a sequence of characters anywhere. It has no idea what a "word" is. Replace art with craft and you also get scraft (from start), pcrafty (from party) and craftist (from artist). In code, renaming id to userId turns width into wuserIdth.

Across one file you would notice. Across a thousand files, these errors hide until someone reads the page.

Option 1: the Match whole word setting

ToolWhere to find it
VS CodeThe ab icon in the search box, or Alt+W
Notepad++Match whole word only checkbox in Find, Replace and Find in Files
Microsoft WordReplace → More → Find whole words only
Bulk ReplaceThe whole-word option on each rule

In most tools the option only applies in normal (plain-text) mode. In Notepad++, for example, Match whole word only is unavailable when Regular expression mode is selected, so use \b in the pattern instead.

Option 2: regex word boundaries

\b matches a position, not a character: the point between a word character (a letter, digit or underscore) and a non-word character (or the start or end of the text).

  • \bcat\b matches cat, cat., (cat) and "cat".
  • It does not match category, bobcat or cat_name, because the underscore is a word character.

In PowerShell:

$t -replace '\bcat\b','dog'

Remember that -replace ignores case, so Cat and CAT change too. Use -creplace to match case exactly.

Only one side

Sometimes you want a word start only. \bpre matches prefix and preview but not spree. Likewise ing\b matches word endings.

Where whole-word matching goes wrong

1. Hyphens and dots are boundaries

Because a hyphen is not a word character, \bcat\b still matches the cat in cat-food and my-cat. Usually fine for prose. In CSS class names, URLs and file names, it can change things you did not intend. To treat hyphens as part of the word, use look-arounds:

(?<![\w-])cat(?![\w-])

That matches cat only when the characters on either side are not letters, digits, underscores or hyphens.

2. Terms that start or end with a symbol

\b.NET\b does not work as expected. There is no word boundary before the dot when it follows a space, because neither a space nor a dot is a word character. The same applies to C++, C#, @handle and #hashtag. Use explicit look-arounds instead:

  • (?<!\w)\.NET\b for .NET
  • \bC\+\+(?!\w) for C++
  • (?<!\w)@acme\b for @acme

Note the escaped \. and \+. Our guide to escaping special characters in regex lists every character that needs it.

3. Accented and non-Latin letters

In .NET (PowerShell and many Windows tools), \w includes accented letters, so \bcaf\b correctly does not match inside café. In some engines, notably standard JavaScript regex, \b treats only A-Z, a-z, 0-9 and underscore as word characters, so accented letters count as boundaries. Check the preview on text with accents.

4. Plurals and other forms

Whole-word widget does not match widgets. That is correct behavior, but it means your plural forms stay unchanged. Either add a rule for each form or use \bwidget(s?)\b → tool$1 to handle both at once.

5. Phrases

Whole word works for phrases too: \bnew york\b matches the phrase but not new yorker. If the words may be separated by a line break or several spaces, use \bnew\s+york\b.

Whole word in PowerShell, step by step

If you are scripting the change, build the pattern from the literal word so special characters are escaped, then add the boundaries:

  1. Set the word and its replacement: $find = 'cat'; $repl = 'dog'
  2. Build the pattern: $pattern = '\b' + [regex]::Escape($find) + '\b'
  3. Replace with case matched exactly: $n = $t -creplace $pattern, $repl
  4. Check the count before writing: ([regex]::Matches($t, $pattern)).Count

If the replacement text could contain a $, escape it as $$ first, because -creplace treats $1 and similar sequences in the replacement as group references. The full file loop is in our guide to replacing text in multiple files with PowerShell.

Code: identifiers need more than whole word

Whole-word matching is the minimum for renaming a variable or function with find and replace, but it does not know about scope. \bcount\b matches every variable called count in every function, plus the word in comments and strings. For distinctive names that is fine; for common names, prefer your IDE's rename refactoring. Our guide to renaming a variable across multiple files goes into this.

A quick test before the real run

Put these words in a scratch file and run your whole-word search against it: cat, Cat, cats, category, bobcat, cat-food, cat_name, (cat), "cat". With \bcat\b and match case on, you should get exactly four matches: cat, cat-food, (cat) and "cat". If the number differs, your tool treats boundaries, case or underscores differently from what you expect, and it is far better to learn that on nine words than on nine thousand files.

Whole-word replace across many files

In Bulk Replace, every rule has its own whole-word and case-sensitive options, so a stack of rules can mix exact-phrase, whole-word and regex matching in one pass. For the edge cases above, switch the rule to regex and use the look-around patterns. The before/after preview shows every match in every file with a total count, which is the quickest way to catch an unexpected cat-food, and you can untick that match before applying. Each run is backed up so it can be undone in one click.

Quick reference

GoalPattern
Whole word\bword\b
Whole word, hyphens count as part of words(?<![\w-])word(?![\w-])
Term starting with a symbol(?<!\w)\.NET\b
Term ending with a symbol\bC\+\+(?!\w)
Word and its plural\bword(s?)\b → new$1
Starts with\bpre\w*

For more patterns like these, see the regex cheat sheet for find and replace.

Frequently asked questions

What does match whole word only do?

It only matches the term when it is not part of a longer word, so replacing cat will not change category or concatenate.

What is the regex for a whole word?

Put \b on each side: \bcat\b. The \b marks a boundary between a word character (letter, digit or underscore) and anything else.

Why does whole word fail with hyphens or symbols?

Hyphens and dots count as boundaries, so whole-word cat still matches in cat-food. A term that starts or ends with a symbol, like .NET, has no word character there for \b to anchor to.

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