Maps

Introduction

A map is Go's built-in key-value collection type, similar to a dictionary in Python, a HashMap in Java, or an object used as a lookup table in JavaScript. Maps give you fast, average O(1) lookups by key, and they're used constantly for things like counting occurrences, caching, and grouping data.

Declaring and Initializing Maps

A map type is written as map[KeyType]ValueType. Maps can be created with a map literal or with the built-in make function. A map declared with var but never initialized is a nil map — you can read from it safely, but writing to it causes a runtime panic.

package main

import "fmt"

func main() {
	// Map literal
	ages := map[string]int{
		"Alice": 30,
		"Bob":   25,
	}
	fmt.Println(ages)

	// make() creates an empty, ready-to-use map
	inventory := make(map[string]int)
	inventory["apples"] = 50
	fmt.Println(inventory)

	// A nil map: reads are safe, writes panic
	var nilMap map[string]int
	fmt.Println(nilMap["missing"]) // prints 0, the zero value — no panic
}

Reading and Writing Values

You read and write map values using square-bracket indexing, just like a slice — except the index is a key instead of a position. Reading a key that doesn't exist returns the zero value for the value type, without any error or panic.

package main

import "fmt"

func main() {
	stock := map[string]int{"pen": 100, "pencil": 200}

	stock["eraser"] = 75      // add a new key
	stock["pen"] = stock["pen"] - 10 // update an existing key

	fmt.Println("pens left:", stock["pen"])
	fmt.Println("staplers:", stock["stapler"]) // key doesn't exist -> 0

	fmt.Println("total distinct items:", len(stock))
}

The Comma-Ok Idiom

Since reading a missing key silently returns the zero value, you can't tell the difference between "the key is missing" and "the key exists but its value happens to be zero" from a single-value read. Go solves this with the comma-ok idiom: indexing a map can return two values — the value, and a boolean indicating whether the key was actually found.

package main

import "fmt"

func main() {
	scores := map[string]int{"Alice": 0, "Bob": 88}

	value, ok := scores["Alice"]
	fmt.Println("Alice:", value, "found:", ok) // found: true, value is genuinely 0

	value, ok = scores["Charlie"]
	fmt.Println("Charlie:", value, "found:", ok) // found: false

	if v, ok := scores["Bob"]; ok {
		fmt.Println("Bob's score is", v)
	}
}

Deleting Keys

The built-in delete function removes a key (and its value) from a map. If the key doesn't exist, delete is a harmless no-op — it never panics.

package main

import "fmt"

func main() {
	cart := map[string]int{"apple": 3, "banana": 2, "cherry": 10}

	delete(cart, "banana")
	fmt.Println(cart)

	delete(cart, "does-not-exist") // safe, does nothing
	fmt.Println(cart)
}

Iterating Over a Map

You can loop over a map's key-value pairs with range. Crucially, Go deliberately randomizes map iteration order on every run — this is intentional, to prevent code from accidentally depending on an order that was never guaranteed. If you need a predictable order, sort the keys yourself first.

package main

import (
	"fmt"
	"sort"
)

func main() {
	population := map[string]int{
		"Tokyo":    37400000,
		"Delhi":    30300000,
		"Shanghai": 27100000,
	}

	// Collect and sort keys for deterministic, repeatable output.
	keys := make([]string, 0, len(population))
	for city := range population {
		keys = append(keys, city)
	}
	sort.Strings(keys)

	for _, city := range keys {
		fmt.Printf("%s: %d\n", city, population[city])
	}
}

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

Maps round out Go's core collection types alongside arrays and slices, giving you fast key-based lookups for the huge number of problems that involve counting, grouping, or caching. The comma-ok idiom is a pattern you'll see reused throughout Go — including with channels and type assertions later on. Next, you'll dig into how Go represents text: strings and runes.