STRING-REPLACE(1) fish-shell STRING-REPLACE(1)

# [NAME](#NAME)

string-replace - replace substrings

# [SYNOPSIS](#SYNOPSIS)

```
string replace [-a | --all] [-f | --filter] [-i | --ignore-case]


               [-r | --regex] [(-m | --max-matches) MAX] [-q | --quiet]


               PATTERN REPLACEMENT [STRING ...]
```

# [DESCRIPTION](#DESCRIPTION)

**string replace** is similar to **string match** but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, *PATTERN* is treated as a literal substring to be matched.

If **-r** or **--regex** is given, *PATTERN* is interpreted as a Perl-compatible regular expression, and *REPLACEMENT* can contain C-style escape sequences like **t** as well as references to capturing groups by number or name as *$n* or *${n}*.

If you specify the **-f** or **--filter** flag then each input string is printed only if a replacement was done. This is useful where you would otherwise use this idiom: **a\_cmd | string match pattern | string replace pattern new\_pattern**. You can instead just write **a\_cmd | string replace --filter pattern new\_pattern**.

If **--max-matches MAX** or **-m MAX** is used, **string replace** will stop all processing after MAX lines of input have matched the specified pattern. In the event of **--filter** or **-f**, this means the output will be MAX lines in length. This can be used as an "early exit" optimization when processing long inputs but expecting a limited and fixed number of outputs that might be found considerably before the input stream has been exhausted.

Exit status: 0 if at least one replacement was performed, or 1 otherwise.

# [EXAMPLES](#EXAMPLES)

## [Replace Literal Examples](#Replace_Literal_Examples)

```
>_ string replace is was 'blue is my favorite'
blue was my favorite
>_ string replace 3rd last 1st 2nd 3rd
1st
2nd
last
>_ string replace -a ' ' _ 'spaces to underscores'
spaces_to_underscores
```

## [Replace Regex Examples](#Replace_Regex_Examples)

```
>_ string replace -r -a '[^\d.]+' ' ' '0 one two 3.14 four 5x'
0 3.14 5
>_ string replace -r '(\w+)\s+(\w+)' '$2 $1 $$' 'left right'
right left $
>_ string replace -r '\s*newline\s*' '\n' 'put a newline here'
put a
here
```

# [Copyright](#Copyright)

fish-shell developers

October 26, 2026 4.9

---

Document: string-replace(1) from fish 4.9.3-r4 (Chainguard OS)
Source: https://github.com/fish-shell/fish-shell