Methods: Value vs Pointer Receivers

Methods attach behavior to types through receivers - either a copy (T) or a pointer (*T).

The choice affects mutability, allocations, interface satisfaction, and API consistency across your package.

Summary

A value receiver copies the struct for the method call.

Mutations inside the method do not affect the caller's copy.

A pointer receiver shares the underlying value.

Mutations persist and avoid copying large structs.

Method sets determine interface satisfaction: value type T only includes methods with value receivers; pointer type *T includes both value and pointer receiver methods.

Pick one receiver style per type unless you have a documented exception.

Use pointer receivers when methods mutate state or when struct size makes copying costly.

Recipe

Quick-reference recipe card - copy-paste ready.

type Buffer struct {
    b []byte
}
 
// Pointer receiver: mutates and matches io.Writer-style APIs.
func (buf *Buffer) Write(p []byte) (int, error) {
    buf.b = append(buf.b, p...)
    return len(p), nil
}
 
// Value receiver: read-only snapshot.
func (buf Buffer) Bytes() []byte {
    return append([]byte(nil), buf.b...)
}
 
// Consistency: if any method needs *T, prefer *T for all methods.
func (buf *Buffer) Reset() { buf.b = buf.b[:0] }

When to reach for this:

• Struct methods mutate fields (Inc, Write, SetState).
• Types implement interfaces requiring pointer methods (fmt.Stringer on large structs is fine either way; sync.Mutex must not copy).
• Value types are small immutable identifiers (time.Time uses value methods).
• You need stable interface satisfaction for both T and *T assignments.

Working Example

package ledger
 
import "fmt"
 
type Account struct {
    id      string
    balance int64
}
 
func NewAccount(id string) *Account {
    return &Account{id: id}
}
 
func (a *Account) Credit(cents int64) error {
    if cents < 0 {
        return fmt.Errorf("ledger: negative credit %d", cents)
    }
    a.balance += cents
    return nil
}
 
func (a Account) Balance() int64 {
    return a.balance
}
 
type Creditor interface {
    Credit(cents int64) error
}
 
func Process(c Creditor, amount int64) error {
    return c.Credit(amount)
}
 
func Example() error {
    acct := NewAccount("user-1")
    if err := Process(acct, 500); err != nil {
        return err
    }
    return nil
}

What this demonstrates:

• Pointer receiver on Credit mutates balance.
• Value receiver on Balance returns a snapshot without exposing mutable state.
• Interface Creditor requires Credit; satisfied by *Account, not Account value.
• Constructor returns *Account so callers land on the pointer method set.

Deep Dive

How It Works

• Methods desugar to functions: a.Credit(x) becomes Credit(a, x) with receiver as first argument.
• Compiler passes address automatically for pointer receivers when variable is addressable.
• Method sets:
  • For type T: methods with receiver T
  • For type *T: methods with receiver T and *T
• Interface assignment checks method set of the dynamic type held.

Receiver Selection Guide

Interface Satisfaction Table

Go Notes

type S struct{ n int }
func (s S) V() int    { return s.n }
func (s *S) P() int   { s.n++; return s.n }
 
var i interface {
    V() int
    P() int
}
// i = S{}   // compile error: S missing P
i = &S{}     // OK

Document constructors returning *T when pointer methods exist.

Gotchas

• Value receiver on mutating method - Changes disappear after call. Fix: switch to *T or return updated copy explicitly.
• Copying structs with mutexes - Value receivers duplicate sync.Mutex and panic. Fix: pointer receivers only; sometimes unexport struct.
• Inconsistent receivers - func (T) Foo and func (*T) Bar breaks T interface assignments. Fix: unify on *T when any pointer method exists.
• Nil pointer receiver calls - Go allows var p *T; p.Method() if method handles nil (see nil guards in stdlib). Fix: document or panic early for invalid nil.
• Interface holds value with pointer methods - Assigning Account value to Creditor fails. Fix: store *Account or add value-receiver wrappers only when semantically sound.
• Embedding pointer types - Promoted methods may require addressable outer struct. Fix: understand promoted method sets when embedding *bytes.Buffer.
• JSON / protobuf generated types - Often use pointers for optional fields; do not mix custom value receivers that copy generated state unexpectedly.

Alternatives

FAQs

Related

• Functions & Methods Basics - first value and pointer method examples
• Defining and Implementing Interfaces - method sets and interface checks
• Nil Interface vs Nil Pointer - pointer methods on nil receivers
• Functions and Interfaces: Go's Composition Model - composition without inheritance
• Functions, Methods & Interfaces Best Practices - receiver consistency rules

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).