Golang Printf and Sprintf: fmt Format Verbs Cheat Sheet

The fmt package has three families of print functions, and each family has the same three variants:

package main

import (
	"fmt"
	"os"
)

func main() {
	name, score := "Ana", 92.456

	fmt.Println("Player", name, "scored", score)
	fmt.Printf("Player %s scored %.1f\n", name, score)

	msg := fmt.Sprintf("%s: %.0f points", name, score)
	fmt.Println(msg, len(msg))

	fmt.Fprintf(os.Stdout, "%-6s|%6.2f|\n", name, score)

	err := fmt.Errorf("player %q not found", "Ben")
	fmt.Println(err)
}

Println adds spaces between operands and a newline at the end. Printf adds nothing: you write \n yourself. Print adds spaces only between operands that are both non-strings, which is surprising enough that most code uses Println or Printf.

Format Verbs

General

package main

import "fmt"

type User struct {
	Name string
	Age  int
	Tags []string
}

func main() {
	u := User{Name: "Ana", Age: 31, Tags: []string{"admin"}}

	fmt.Printf("%v\n", u)
	fmt.Printf("%+v\n", u)
	fmt.Printf("%#v\n", u)
	fmt.Printf("%T\n", u)
	fmt.Printf("%v\n", &u)

	m := map[string]int{"b": 2, "a": 1}
	fmt.Printf("%v %#v\n", m, m)
}

%+v is the one to reach for when debugging. A pointer to a struct prints as &{...} rather than an address. Maps print with keys sorted, so output is stable even though map iteration order is random.

Integers

Floats

%.2f rounds the float's exact binary value, so fmt.Sprintf("%.2f", 2.675) is 2.67: the nearest float64 to 2.675 is slightly below it. Never format money from a float; keep cents in an integer.

Strings and bytes

%s on a []byte prints it as text; %v prints the numbers ([104 105]).

Other types

Width, Precision and Padding

Between % and the verb you can put flags, a width and a precision:

package main

import "fmt"

func main() {
	fmt.Printf("|%5d|%-5d|%05d|\n", 42, 42, 42)
	fmt.Printf("|%8.2f|%-8.2f|%.0f|\n", 3.14159, 3.14159, 2.5)
	fmt.Printf("|%10s|%-10s|%.3s|\n", "gopher", "gopher", "gopher")
	fmt.Printf("|%+d|%+d|\n", 5, -5)
	fmt.Printf("|%*d|\n", 7, 42) // width from an argument

	fmt.Println()
	items := []struct {
		name  string
		price float64
	}{{"Keyboard", 49.9}, {"Mouse", 19.5}, {"Monitor", 229}}
	for _, it := range items {
		fmt.Printf("%-10s %8.2f\n", it.name, it.price)
	}
}

Note %.0f of 2.5 prints 2: Go rounds half to even here. Width counts runes for strings, not display columns, so CJK characters and emoji can still misalign a table. For aligned columns of variable text, text/tabwriter does the measuring for you.

Argument indexes

%[n] picks an argument by position, which lets you reuse one:

fmt.Printf("%[2]s %[1]s\n", "world", "hello") // hello world
fmt.Printf("%d %[1]x %[1]b\n", 10)             // 10 a 1010

Errorf and %w

fmt.Errorf builds an error from a format string. With %w it also wraps another error, so callers can still detect the original:

package main

import (
	"errors"
	"fmt"
	"os"
)

func loadConfig(path string) error {
	_, err := os.Open(path)
	if err != nil {
		return fmt.Errorf("load config %s: %w", path, err)
	}
	return nil
}

func main() {
	err := loadConfig("/no/such/file.yaml")
	fmt.Println(err)
	fmt.Println("not exist?", errors.Is(err, os.ErrNotExist))

	// %v formats the same text but does not wrap
	flat := fmt.Errorf("load config: %v", os.ErrNotExist)
	fmt.Println("wrapped?", errors.Is(flat, os.ErrNotExist))
}

Use %w when callers may need to check the cause, and %v when you deliberately hide it. Since Go 1.20 one Errorf call may contain several %w verbs. The error handling page covers wrapping in depth.

Custom Formatting with String()

Any type with a String() string method controls how %v, %s and Println show it:

package main

import "fmt"

type Money int64 // cents

func (m Money) String() string {
	return fmt.Sprintf("$%d.%02d", m/100, m%100)
}

func main() {
	price := Money(129950)
	fmt.Println(price)
	fmt.Printf("%v | %s | %d\n", price, price, price)
}

%d bypasses String() and prints the underlying number. For error types the equivalent method is Error() string, which takes precedence over String().

When the Verb Is Wrong

fmt never panics on a bad format. It prints the problem inline:

fmt.Printf("%d\n", "oops")
fmt.Printf("%d %d\n", 1)
fmt.Printf("%d\n", 1, 2)

%!d(string=oops)
1 %!d(MISSING)
1
%!(EXTRA int=2)

That output tends to reach production because it does not crash anything. go vet catches all three at build time:

./main.go:8:2: fmt.Printf format %d has arg "oops" of wrong type string
./main.go:9:2: fmt.Printf format %d reads arg #2, but call has 1 arg
./main.go:10:2: fmt.Printf call needs 1 arg but has 2 args

Performance Notes

fmt takes every argument as an any and inspects its type at run time (falling back to reflection for structs, slices and maps), which is fine for logging and output but measurable in tight loops. For converting a single number, strconv.Itoa and strconv.FormatFloat are faster than Sprintf. For building a long string in a loop, write into a strings.Builder with fmt.Fprintf(&b, ...) instead of concatenating Sprintf results.