---
page_title: replace - Functions - Configuration Language
description: |-
  The replace function searches a given string for another given substring,
  and replaces all occurrences with a given replacement string.
---

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
> [!IMPORTANT]  
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️


# `replace` Function

`replace` searches a given string for another given substring, and replaces
each occurrence with a given replacement string.

```hcl
replace(string, substring, replacement)
```

If `substring` is wrapped in forward slashes, it is treated as a regular
expression, using the same pattern syntax as
[`regex`](/terraform/language/functions/regex). If using a regular expression for the substring
argument, the `replacement` string can incorporate captured strings from
the input by using an `$n` sequence, where `n` is the index or name of a
capture group.

## Examples

```
> replace("1 + 2 + 3", "+", "-")
1 - 2 - 3

> replace("hello world", "/w.*d/", "everybody")
hello everybody
```

## Related Functions

- [`regex`](/terraform/language/functions/regex) searches a given string for a substring matching a
  given regular expression pattern.