HOWTO · PowerShell

How to Replace Strings in PowerShell

The tutorial shows how to utilize the PowerShell replace method and PowerShell replace operator.

On this page

PowerShell offers two useful ways to change text in a string value: the .NET String.Replace method for literal text and the -replace operator for regular-expression patterns. Both produce a string you can save, display, or pass to another operation; these examples work with values in memory and do not edit files.

How PowerShell String Replacement Works

A replacement takes a source string, a search value or pattern, and replacement text. In the example below, $string holds the original text and $result holds the changed value. PowerShell writes the result as selectable text.

Run this example:

$string = 'hello, world'
$result = $string.Replace('hello', 'hi')
Write-Output $result

The search term is hello; the replacement is hi. The original variable remains available because the method result is assigned separately. Use String.Replace when the search should match those literal characters, and use -replace when the search should describe a pattern.

Replace Literal Text with the String.Replace Method

String.Replace is a method on a string, not a PowerShell function. It accepts the text to find and the text to substitute. Its search is literal and case-sensitive: characters such as . have no special meaning, and uppercase and lowercase letters are distinct. The method returns a string. If the search text is absent, that returned string is unchanged.

You can call the method on a variable or directly on a quoted string. This standalone example calls it on a variable:

$string = 'hello, world'
$result = $string.Replace('world', 'PowerShell')
Write-Output $result

The original $string value is not modified in place. Assigning the returned string to $string is also valid when you want the variable itself to hold the new value.

Remove Text and Chain String.Replace Calls

To remove a literal substring, pass an empty string ('') as the replacement. Each call returns a string, so a second method call can operate on the first call’s result. The operations happen from left to right.

$string = 'hello, world'
$result = $string.Replace('hello', '').Replace('world', 'globe')
Write-Output $result

This pattern is useful for a short sequence of literal substitutions. For a larger set of unrelated literal terms, consider a clear sequence of calls or a mapping-driven approach; -replace is not automatically simpler because its search text has pattern syntax.

Use the -replace Operator for Pattern Matching

PowerShell’s -replace is an operator that takes the input string on the left and a regular-expression pattern as its first right-side argument, followed by the replacement text. For example, in $string -replace 'pattern', 'replacement', $string is the input and 'pattern' is the search pattern. The operator replaces every match. Matching is case-insensitive by default; the case-sensitive -creplace variant is available when capitalization must match. In a regular expression, characters such as . and * are operators rather than ordinary text.

This example replaces each run of digits with a marker:

$string = 'Order 17, shelf 204'
$result = $string -replace '\d+', '[number]'
Write-Output $result

When a -replace pattern should match literal text that contains regex metacharacters, escape those characters with [regex]::Escape():

$string = 'file.name and fileXname'
$pattern = [regex]::Escape('file.name')
$result = $string -replace $pattern, 'document'
Write-Output $result

Here the period is part of the literal search text, so the pattern does not treat it as a wildcard. Choose the operator for pattern matching or when its case-insensitive default is desired; choose -creplace when the same pattern should match case-sensitively.

Remove Text and Chain -replace Operations

An empty replacement also removes matches with -replace. To apply multiple changes, place another -replace operation after the first; it receives the first operation’s returned string. The search side of each operation remains a regular expression.

$string = 'hello, world'
$result = $string -replace 'hello', '' -replace 'world', 'globe'
Write-Output $result

If a pattern includes parentheses, brackets, a period, or other regex syntax that should be literal, escape the literal search text before using it. This prevents a removal or chained replacement from matching more text than intended.

Choose Between String.Replace and -replace

Use String.Replace for exact literal text and case-sensitive matching; its result is unchanged when the literal search is absent. Use -replace for regular-expression matching and its default case-insensitive behavior, or use -creplace for case-sensitive pattern matching. Both approaches return a string and can be assigned or chained. For a literal search with -replace, escape the pattern with [regex]::Escape(); for a simple literal substitution, String.Replace avoids regex syntax altogether.