# What Is the `maps.Clone` Function in Go 1.21?

> Discover maps.Clone in Go 1.21 for efficient map cloning. This standard library function creates a shallow copy, simplifying your code by replacing manual loops.

- Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines)
- Tags: deep-dive
- Published: 2026-08-29

---

**`maps.Clone` creates a shallow copy of a map in a single standard library call, returning `nil` if the source is `nil` and eliminating the need for manual iteration loops.**

Introduced in Go 1.21, the `maps.Clone` function provides a standardized way to duplicate map headers without deep-copying the underlying key-value pairs. Prior to this addition, developers relied on boilerplate `make` and `range` loops to copy maps, leading to verbose and error-prone implementations. According to the [JetBrains/go-modern-guidelines](https://github.com/JetBrains/go-modern-guidelines) repository, adopting this helper clarifies intent while preserving critical nil semantics that manual implementations often accidentally destroy.

## How `maps.Clone` Works

`maps.Clone` performs a **shallow copy** of the source map, allocating a new map header while referencing the same keys and values stored in the original.

- **Shallow semantics**: Only the map structure is duplicated; keys and values are not recursively copied. For complex types like slices or pointers, the cloned map shares the same underlying data as the source.
- **Nil preservation**: If the input map is `nil`, `maps.Clone` returns `nil` rather than an initialized empty map. This maintains type safety and prevents accidental allocations that change program logic.
- **Optimized implementation**: The function uses the Go runtime's internal map iteration machinery, often outperforming hand-written loops by pre-allocating the appropriate capacity based on the source map's size.

## Why Prefer `maps.Clone` Over Manual Copying

The go-modern-guidelines project documents several advantages of using the standard library helper instead of manual copying.

**Clarity**: A single function call expresses the operation's intent more clearly than a three-line initialization and iteration loop, improving readability for maintainers reviewing the code.

**Safety**: Manual implementations often accidentally convert `nil` maps into empty maps via `make()`, destroying the semantic distinction between an uninitialized map and an empty one. `maps.Clone` preserves this distinction by propagating `nil` values correctly.

**Maintainability**: Centralizing the copy logic in the standard library ensures that future optimizations or semantic changes to map copying are applied globally without requiring modifications to application code.

**Performance**: The runtime implementation leverages optimized memory allocation and iteration strategies that are difficult to replicate efficiently in user-space Go code.

## Source Code Context

The rationale for using `maps.Clone` is formally defined in the repository's guideline files and feature documentation.

**[`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json)** (lines 36-51): Contains the formal specification for the `mapsclone` rule, describing the transformation from manual loops to the standard library call and explaining the safety benefits regarding nil handling.

**[`FEATURES.md`](https://github.com/JetBrains/go-modern-guidelines/blob/main/FEATURES.md)** (lines 35-55): Provides concrete before-and-after code comparisons and specifies the Go version requirement (1.21+), illustrating how the function eliminates boilerplate while maintaining correctness.

## Practical Usage Examples

### Migrating from Manual Copying (Pre-Go 1.21)

Before Go 1.21, copying a map required explicit allocation and iteration:

```go
copied := make(map[string]int, len(src))
for k, v := range src {
    copied[k] = v
}

```

With Go 1.21 and later, the standard library simplifies this to a single call:

```go
import "maps"

copied := maps.Clone(src)

```

### Handling Nil Maps Safely

When working with potentially uninitialized maps, `maps.Clone` preserves the nil state rather than creating an empty map:

```go
var src map[string]int // src is nil
clone := maps.Clone(src) // clone is also nil, not map[]

if clone == nil {
    // This branch executes, unlike with manual make()
}

```

### Copying Maps with Struct Values

For maps containing structs, `maps.Clone` performs a shallow copy of the values. The struct values themselves are copied, but any pointer fields within them are shared:

```go
type Person struct {
    Name string
    Age  int
}

original := map[string]Person{
    "alice": {"Alice", 30},
    "bob":   {"Bob", 25},
}

// Shallow copy – struct values are independent, but pointer fields would be shared
clone := maps.Clone(original)

```

## Summary

- **`maps.Clone`** is available in the standard library `maps` package starting with Go 1.21.
- It creates a **shallow copy** of a map, duplicating only the header structure while sharing keys and values with the source.
- **Nil maps** remain `nil` after cloning, avoiding accidental conversion to empty maps that occurs with `make()`.
- The implementation is optimized in the Go runtime and generally outperforms manual `range` loops.
- The JetBrains/go-modern-guidelines repository recommends this function in [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json) to replace verbose copying boilerplate.

## Frequently Asked Questions

### What is the difference between `maps.Clone` and a manual copy loop?

**`maps.Clone` is a single function call that handles allocation, iteration, and nil-checking automatically.** A manual loop requires writing `make(map[K]V, len(src))` followed by a `for k, v := range src` iteration, which is error-prone and obscures the programmer's intent. Additionally, manual implementations often accidentally allocate empty maps when the source is nil, whereas `maps.Clone` preserves nil semantics as documented in the repository's [`FEATURES.md`](https://github.com/JetBrains/go-modern-guidelines/blob/main/FEATURES.md).

### Does `maps.Clone` perform a deep copy?

**No, `maps.Clone` performs a shallow copy.** It creates a new map header and copies references to the existing keys and values. If your map contains slices, maps, or pointers, the cloned map will reference the same underlying data structures. Deep copying requires implementing custom logic for your specific value types.

### What happens if I clone a nil map?

**`maps.Clone` returns `nil` when the input map is `nil`.** This behavior differs from manually creating a map with `make()`, which produces an empty but initialized map. Preserving the nil state is crucial for APIs that distinguish between "unset" and "empty" map states, as emphasized in the guideline specification at [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json).

### When should I use `maps.Clone` instead of `maps.Copy`?

**Use `maps.Clone` when you need to create a new, independent map containing all entries from the source.** Use `maps.Copy` when you want to add entries from a source map into an existing destination map. `maps.Clone` handles allocation and nil-safety automatically, while `maps.Copy` requires you to initialize the destination map beforehand.