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.