Go Methods: Value vs Pointer Receivers, Method Sets, and Expressions
Value and pointer receivers, the method sets they produce, why map elements cannot call pointer methods, and method values that capture a copy.

A method is a function with a receiver, and the receiver's form decides two things that are easy to conflate: whether the method can modify the original value, and whether the type satisfies an interface. A value receiver gets a copy, so mutations are lost; a pointer receiver shares the original, so mutations stick. The method set — the set of methods callable on a type — then determines interface satisfaction, and it differs between T and *T in exactly one direction: *T has every method, T has only the value-receiver ones.
Quick Summary
func (t T) M()copies the receiver;func (t *T) M()receives the address and can mutate.- The method set of
*Tincludes methods with either receiver; the method set ofTincludes only value receivers. - So
*Tcan satisfy an interface thatTcannot, and that is the most common source ofmethod has pointer receivererrors. v.M()with a pointer receiver compiles whenvis addressable: the compiler rewrites it to(&v).M().- Map elements, function return values, and interface values are not addressable, so pointer-receiver methods cannot be called on them.
t.Mas a value binds a copy of the receiver at that moment; it does not read the receiver again when called.T.Mas an expression is a plain function taking the receiver as its first argument.- Once any method needs a pointer receiver, give the type pointer receivers throughout, or the type and its pointer will have different method sets and behave differently in interfaces.
Basic syntax and type signatures
type Counter struct {
n int
}
func (c Counter) Value() int { return c.n } // copy
func (c *Counter) Inc() { c.n++ } // mutates the original
func (c *Counter) Reset() { c.n = 0 }
func use() {
var c Counter
c.Inc() // (&c).Inc()
c.Inc()
fmt.Println(c.Value(), c.n) // 2 2
p := &c
p.Inc() // no rewrite needed
fmt.Println(p.n) // 3
}// Method expression: receiver becomes the first parameter.
inc := (*Counter).Inc // func(*Counter)
inc(&c)
val := Counter.Value // func(Counter) int
fmt.Println(val(c)) // works on a copy
// Method value: receiver bound now.
get := c.Value // func() int, bound to a copy of c at this moment
c.Inc()
fmt.Println(get(), c.Value()) // 3 4 — the bound copy did not changeReceivers must be declared in the same package as the type, and the type must be a defined type, not a pointer or an interface:
type MyInt int
func (m MyInt) Double() MyInt { return m * 2 } // ok
// func (s string) Len() int { ... } // cannot define new methods on non-local type string
// type Alias = MyInt
// func (a Alias) X() {} // invalid receiver type Alias (alias, not defined type)Comparison of receiver forms
| Aspect | func (t T) | func (t *T) |
|---|---|---|
| Receiver contents | copy of the value | pointer to the value |
| Mutations visible to caller | no | yes |
Method in method set of T | yes | no |
Method in method set of *T | yes | yes |
| Callable on a non-addressable value | yes | no (compile error) |
| Nil receiver allowed | n/a | yes, if the method checks for nil |
| Cost per call | copy of the value | pointer copy |
Safe to copy in go vet terms | yes | the receiver itself is a pointer, the pointee may hold a lock |
| Typical use | small immutable values, string-like types | structs with state, locks, large values |
The rule of thumb: if any method mutates, all methods take pointers; if the type is a small immutable value (a wrapper around a number, an error type, a time.Time-like struct), value receivers are simpler and avoid nil handling. Mixing the two on one type is legal and is where interface surprises come from.
Practical edge cases and deep dives
1. Value receivers copy, including the parts that look like references
type Buffer struct {
data []byte
n int
}
func (b Buffer) Append(p []byte) { // value receiver
b.data = append(b.data, p...) // reassigns the copy's slice header
b.n += len(p) // lost
}
func (b Buffer) MutateFirst() {
if len(b.data) > 0 {
b.data[0] = 'X' // visible: the backing array is shared
}
}
func (b *Buffer) AppendFixed(p []byte) {
b.data = append(b.data, p...)
b.n += len(p)
}
b := Buffer{data: make([]byte, 0, 10)}
b.Append([]byte("hi"))
fmt.Println(len(b.data), b.n) // 0 0 — the header reassignment was lost
b.AppendFixed([]byte("hi"))
fmt.Println(len(b.data), b.n) // 2 2A slice is a three-word header, and copying the struct copies the header while sharing the backing array. That produces the most confusing class of value-receiver bug: MutateFirst visibly changes the caller's data, so the receiver "obviously" shares state, and then Append silently loses the length. Whether a value-receiver method can mutate depends on which part of the value is a reference — a rule worth avoiding by using pointer receivers for anything mutable.
2. Method sets and interface satisfaction
type Speaker interface {
Speak() string
}
type Dog struct{ name string }
func (d Dog) Speak() string { return d.name + ": woof" }
func (d *Dog) Rename(n string) { d.name = n }
var _ Speaker = Dog{} // ok: Speak has a value receiver
var _ Speaker = &Dog{} // ok: *Dog's method set includes it
type Cat struct{ name string }
func (c *Cat) Speak() string { return c.name + ": meow" }
// var _ Speaker = Cat{} // compile error: Cat does not implement Speaker
// // (method Speak has pointer receiver)
var _ Speaker = &Cat{} // okThe error text is cannot use Cat{} (variable of type Cat) as Speaker value in variable declaration: Cat does not implement Speaker (method Speak has pointer receiver). It appears whenever a value is stored in an interface and the method needs a pointer — including a function parameter of interface type, a slice of interfaces, and a map value of interface type. Storing &Cat{} fixes it, and the fix is a real decision: the interface now holds a pointer, so a copy of the interface shares the Cat.
The consequence shows up in constructors that return interfaces:
func NewCat(name string) Speaker {
return &Cat{name: name} // returning Cat would not compile
}3. Non-addressable receivers: map elements and return values
type Item struct{ Count int }
func (i *Item) Inc() { i.Count++ }
m := map[string]Item{"a": {}}
// m["a"].Inc() // compile error: cannot call pointer method Inc on Item value m["a"]
items := []Item{{}, {}}
items[0].Inc() // ok: slice elements are addressable
fmt.Println(items[0].Count) // 1
func makeItem() Item { return Item{} }
// makeItem().Inc() // compile error: cannot call pointer method on makeItem()
ptrMap := map[string]*Item{"a": {}}
ptrMap["a"].Inc() // ok: the map value is a pointer, and the pointee is addressable
fmt.Println(ptrMap["a"].Count) // 1A map element is not addressable because the map may rehash and move it, so &m[k] is not allowed and neither is the implicit & of a pointer-receiver call. The workarounds are a map of pointers (usually the right one when the elements are mutable), a read-modify-write (it := m["a"]; it.Inc(); m["a"] = it), or a map of a small value type with value-receiver methods that return the modified copy.
4. Method values capture the receiver at evaluation time
type Logger struct{ prefix string }
func (l Logger) Log(msg string) { fmt.Println(l.prefix, msg) }
func (l *Logger) SetPrefix(p string) { l.prefix = p }
l := Logger{prefix: "v1"}
f := l.Log // bound to a COPY of l
l.SetPrefix("v2")
f("hello") // prints "v1 hello"
g := l.Log // new binding, now "v2"
g("hello") // prints "v2 hello"
// The classic loop bug with method values:
var fns []func()
for i := 0; i < 3; i++ {
l := Logger{prefix: fmt.Sprint(i)}
fns = append(fns, l.Log) // each closure holds its own copy
}
for _, fn := range fns { fn("x") } // 0 x, 1 x, 2 xA method value on a pointer receiver binds the pointer, so changes through that pointer are visible; a method value on a value receiver binds a copy, so later mutations are invisible. Both behaviors are useful and both are invisible at the call site, which is why passing obj.Method as a callback deserves a second look when the object is mutable.
5. Nil receivers, String(), and copied locks
type List struct {
head *node
size int
}
func (l *List) Len() int {
if l == nil {
return 0
}
return l.size
}
var nilList *List
fmt.Println(nilList.Len()) // 0: calling a method on a nil pointer is legal
type Config struct{ path string }
func (c *Config) String() string { return c.path }
cfg := Config{path: "/etc"}
fmt.Println(cfg) // {/etc} — not "/etc": String has a pointer receiver
fmt.Println(&cfg) // /etc
type Service struct {
mu sync.Mutex
n int
}
func (s Service) Bad() {} // go vet: Bad passes lock by value
func (s *Service) Good() {}fmt receives its argument as an interface; a Config value's method set does not include String(), so the formatter falls back to the struct's default formatting, while &cfg does implement it. That single asymmetry explains most "my String() method is ignored" reports. The go vet check on a value receiver of a struct containing a sync.Mutex is the same problem from the other direction: the copy is a second, independent lock over shared state, and the protection quietly stops working.
Common mistakes and compiler errors
| Error or symptom | Cause | Fix |
|---|---|---|
cannot use t (variable of type T) as I value: T does not implement I (method M has pointer receiver) | method set of T lacks pointer methods | pass &t, or switch the method to a value receiver |
cannot call pointer method M on T | receiver not addressable (map element, call result) | store pointers, or copy out and back |
cannot take the address of m[k] | map elements are not addressable | use a pointer map |
| Mutation in a value-receiver method has no effect | receiver is a copy | pointer receiver |
| Mutation partly works for slices/maps | the copy shares the backing array | pointer receiver for anything mutable |
A String()/Error() method is ignored | pointer receiver, value passed to fmt or error | define it on the value receiver, or pass the pointer |
go vet: passes lock by value | value receiver copies a struct containing a mutex | pointer receiver |
| Method value sees stale fields | receiver copy captured at evaluation | bind the pointer, or call the method directly |
| Loop callbacks all use the last value | shared variable captured | declare a per-iteration variable |
invalid receiver type | receiver is a pointer alias or an interface | use a defined type in the same package |
The design decision is worth making once per type rather than per method. If the type holds state that any method changes, or contains a lock, a map, a slice, or a channel, use pointer receivers everywhere and construct with &T{...}; the method set then matches the type's actual semantics, interfaces work with a single form, and no caller has to wonder whether a copy is happening. Reserve value receivers for small values that are conceptually immutable — a Money amount, a coordinate, an error value — where a copy is exactly what you want and T satisfying the interface is a feature rather than a trap.
Try matching browser tools
All toolsSmall utilities that fit Go work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Go guides
All Go guidesGo iota: Enumerations, Bitmask Flags, and Constant Expressions
How iota advances per const line, typed enums with gaps, bit flags with 1 << iota, and the unit scale pattern that shifts with one blank line.
Go JSON: Marshaling, Unmarshaling, Struct Tags, and Custom Parsers
Struct tags, omitempty that skips false and zero, custom marshalers without recursion, RawMessage for tagged unions, and float64 precision loss.
Go Strings, Runes, and Bytes: UTF-8 Encoding, Conversion, and Memory
Bytes versus runes, len that counts bytes, slicing that splits characters, Builder for linear concatenation, and normalization the standard library omits.
Go select Statement: Non-Blocking Operations, Timeouts, and Nil Channels
Random choice among ready cases, non-blocking polls with default, nil channels that disable a case, timer reuse, and labeled breaks out of a loop.
More in Go
All Go guidesThe guides filed next to this one in Go, in library order.