Deleting Keys from a Map During range in Go

By the end of this page, you will understand how Go map iteration behaves, whether deleting keys during a range loop is safe, what Go guarantees about that behavior, and which deletion patterns are best for real programs.

In Go, a map is a built-in hash table structure used to store key-value pairs. You often iterate over a map using for ... range and remove entries with delete(map, key).

The key idea is:

• Deleting from a map during iteration is safe in Go.
• Go specifically allows delete(m, key) while ranging over m.
• If a map entry has not yet been reached during iteration and you delete it, that entry will not be produced later.
• If you delete the current key, that is also safe.

This matters because many languages either forbid modifying a collection during iteration or make the behavior undefined. Go is more explicit here for deletion.

However, there is an important distinction:

• Deleting entries during iteration is safe.
• Adding new entries during iteration has unpredictable iteration results for those new entries.

So the main rule is: if your goal is to remove matching items from a Go map, deleting inside a range loop is a normal and idiomatic approach.

A second thing to remember is that map iteration order in Go is not guaranteed. That means the order in which keys are visited and deleted is arbitrary.

In short:

• Safe to delete while ranging: yes
• Safe to rely on iteration order: no
• Safe to expect newly inserted items to always appear in the same loop: no

Think of a Go map like a basket of labeled cards.

• range means: “keep pulling cards from the basket in whatever order the basket gives them.”
• delete(table, key) means: “remove this card from the basket.”

If you remove a card that you already pulled, no problem. If you remove a card that is still in the basket waiting to be pulled, it simply will not be pulled later.

What you should not imagine is a neatly ordered list. A Go map is not a line of items with fixed positions. It is more like a shuffled container. That is why deletion is fine, but order is unpredictable.

The basic deletion syntax is:

delete(myMap, key)

If the key exists, it is removed. If the key does not exist, delete does nothing.

Deleting selected keys while ranging

package main

import "fmt"

func main() {
    scores := map[string]int{
        "alice": 90,
        "bob":   40,
        "carl":  75,
        "dina":  30,
    }

    for name, score := range scores {
        if score < 50 {
            delete(scores, name)
        }
    }

    fmt.Println(scores)
}

This safely removes entries where the score is below 50.

Deleting everything from a map

for key := range myMap {
    delete(myMap, key)
}

This is a valid way to clear a map entry by entry.

Consider this example:

package main

import "fmt"

func main() {
    m := map[string]int{
        "a": 1,
        "b": 2,
        "c": 3,
    }

    for k, v := range m {
        fmt.Println("visiting", k, v)
        if v%2 == 1 {
            fmt.Println("deleting", k)
            delete(m, k)
        }
    }

    fmt.Println("final:", m)
}

A possible run might behave like this:

1. The loop starts iterating over m.
2. Suppose Go visits b first.
   • Prints visiting b 2
   • 2 % 2 == 0, so nothing is deleted.
3. Suppose Go visits a next.
   • Prints visiting a 1

Deleting map keys during iteration is useful in many real programs.

Removing expired cache entries

for key, item := range cache {
    if item.Expired() {
        delete(cache, key)
    }
}

Filtering invalid API results

After loading a set of objects into a map, you may remove entries that fail validation.

for id, user := range users {
    if user.Email == "" {
        delete(users, id)
    }
}

Cleaning feature flags or configuration

for name, enabled := range flags {
    if !enabled {
        delete(flags, name)
    }
}

Removing completed jobs from an in-memory tracker

for id, job := range jobs {
    if job.Done {
        delete(jobs, id)
    }
}

Pruning temporary session data

Maps are often used for in-memory session stores. Expired sessions can be deleted while scanning the map.

In real Go codebases, developers commonly use deletion during map iteration in simple cleanup passes.

Pattern: in-place filtering

Instead of building a second map, you can keep the original one and remove unwanted entries.

for key, value := range m {
    if shouldRemove(value) {
        delete(m, key)
    }
}

This is useful when:

• you want to save memory
• the map is already owned by the current function
• preserving the original map is not required

Pattern: guard clause before delete

for key, value := range m {
    if value == nil {
        delete(m, key)
        continue
    }

    if value.IsInvalid() {
        delete(m, key)
    }
}

This keeps cleanup logic clear and local.

Pattern: validation and normalization pass

A map may be populated first, then cleaned.

for key, cfg := range configs {
    if cfg.Name == "" {
        delete(configs, key)
    }
}

Pattern: collect keys first when logic is complex

Mistake 1: Thinking map iteration order is fixed

Broken assumption:

for k := range m {
    fmt.Println(k) // expecting alphabetical or insertion order
}

Avoid this by remembering:

• Go map iteration order is unspecified.
• If you need order, copy keys to a slice and sort them.

Mistake 2: Confusing deletion safety with concurrent safety

This is a very common misunderstanding.

Broken idea:

// Goroutine 1
for k := range m {
    delete(m, k)
}

// Goroutine 2
fmt.Println(m["x"])

This is unsafe without synchronization if both access the map at the same time.

Avoid this by using:

• sync.Mutex
• sync.RWMutex
• sync.Map when appropriate
• channel-based ownership patterns

Mistake 3: Expecting inserted items to behave predictably during the same loop

for k := range m {
    m[] = 
    fmt.Println(k)
}

Delete in place vs build a new map

// Delete one key
delete(m, key)

// Delete matching keys while ranging
for k, v := range m {
    if shouldRemove(v) {
        delete(m, k)
    }
}

// Clear a map
for k := range m {
    delete(m, k)
}

Key rules:

• Deleting from a Go map during range is safe.
• Deleted entries not yet reached will not be visited later.
• Map iteration order is not guaranteed.
• Inserting during iteration is allowed, but do not rely on whether new entries appear.
• Plain maps are not safe for concurrent read/write access.
• delete(m, missingKey) is valid and does nothing.

When to use this pattern:

• remove expired items
• filter invalid entries
• clean up in-memory state
• clear a map

When not to rely on it:

• when you need sorted or stable ordering
• when multiple goroutines touch the same map without locking

Can you delete from a map while iterating in Go?

Yes. Go allows deleting keys from a map during a for ... range loop over that same map.

What happens if a key is deleted before the loop reaches it?

It will not be produced later in that iteration.

Is deleting the current key safe in a range loop?

Yes. Deleting the key currently being visited is safe.

Can I add keys to a map during iteration?

You can, but the iteration behavior for newly added keys is not something you should depend on.

Does deleting while ranging preserve any order?

No. Go maps do not have guaranteed iteration order.

How do I remove all keys from a map?

A common pattern is:

for k := range m {
    delete(m, k)
}

Is this safe with goroutines?

Not by itself. Regular Go maps need synchronization if multiple goroutines read and write at the same time.

Should I delete in place or create a new map?

Delete in place if you want to mutate the existing map simply. Build a new map if you need to keep the original or want a clearer transformation pipeline.

• for range in Go — because map iteration uses range syntax.
• Go maps — the underlying data structure being iterated and modified.
• delete built-in function — the operation used to remove keys.
• Map iteration order — important because Go does not guarantee ordering.
• Zero values in Go — useful when reading missing map keys.
• Comma-ok idiom — commonly used to test whether a map key exists.
• Concurrency and mutexes in Go — important because maps are not safe for unsynchronized concurrent access.
• Slices vs maps — useful when comparing how removal during iteration differs between collection types.