Guide · Open source

How to use zap: install and log in Go

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Zap is an open-source logging library for Go from Uber. It writes leveled log messages with key-value details attached, so logs are easy to search and analyze. This guide shows you how to install it, pick one of its two APIs, and write your first structured log lines.

zapuber-go/zap · ★ 24.7k · MIT Install options & downloads

Quick start

1Install zap. Run go get -u go.uber.org/zap inside your Go module.
2Pick an API. Use the SugaredLogger for convenience or the Logger for typed, lowest-overhead logging.
3Create a logger. Call zap.NewProduction and defer Sync to flush buffered output.
4Write a log line. Add a message and key-value fields, using Infow or Info depending on the API you chose.
5Check the output. Run your program and confirm that each log entry has its level and attached fields.

Install zap into a Go module

Zap is installed as a Go dependency. Run the install command from the root of your Go module. Zap only supports the two most recent minor versions of Go, so check that your Go toolchain is current.

go get -u go.uber.org/zap

Choose between SugaredLogger and Logger

Zap offers two APIs. The SugaredLogger is looser and more convenient: it accepts loosely typed key-value pairs and includes both structured and printf-style methods. The Logger is faster and allocates far less, but it only supports structured logging with strongly typed fields.

Use the SugaredLogger where performance is nice but not critical. Use the Logger when performance and type safety are critical.

SugaredLogger: loosely typed key-value pairs, plus printf-style methods
Logger: strongly typed Field values such as zap.String, zap.Int and zap.Duration, structured logging only

Log with the SugaredLogger

Create a logger with zap.NewProduction, defer Sync to flush any buffered output, then call Sugar() to get the SugaredLogger. Pass a message followed by key-value pairs with Infow, or use Infof for a printf-style message.

logger, _ := zap.NewProduction()
defer logger.Sync() // flushes buffer, if any
sugar := logger.Sugar()
sugar.Infow("failed to fetch URL",
  // Structured context as loosely typed key-value pairs.
  "url", url,
  "attempt", 3,
  "backoff", time.Second,
)
sugar.Infof("Failed to fetch URL: %s", url)

Log with the strongly typed Logger

When you want type safety and the lowest overhead, call the Logger directly. Each field is a typed value built with a helper such as zap.String, zap.Int or zap.Duration.

logger, _ := zap.NewProduction()
defer logger.Sync()
logger.Info("failed to fetch URL",
  // Structured context as strongly typed Field values.
  zap.String("url", url),
  zap.Int("attempt", 3),
  zap.Duration("backoff", time.Second),
)

Understand the performance trade-off

Zap includes a reflection-free, zero-allocation JSON encoder, and the base Logger avoids serialization overhead and allocations where possible. The README's own benchmarks show zap ahead of comparable structured logging packages and the standard library, but it advises taking benchmark numbers with a grain of salt. Measure your own application before deciding.

Read the documentation and FAQ

The full API reference is on pkg.go.dev, and the project has a FAQ file in its repository. These cover details beyond the quick start, such as the rest of the logger configuration options.

What people use it for

Logging request failures in a web service with the URL, attempt count and backoff attached as fields
Writing machine-readable structured logs that a log search tool can filter by key
Keeping logging overhead low in hot code paths of a busy server
Mixing printf-style messages with structured fields in the same codebase using the SugaredLogger

Frequently asked questions

Is zap free to use?

Yes. zap is released under the MIT License, which is a permissive open-source licence. The source does not mention any paid tier.

What do I need to install zap?

You need Go and a Go module to install it into. The README notes that zap only supports the two most recent minor versions of Go, so use a current Go release.

How do I install zap?

Run go get -u go.uber.org/zap from your Go module. This adds zap as a dependency of your project.

What is the difference between SugaredLogger and Logger in zap?

SugaredLogger is looser and more convenient, with key-value pairs and printf-style methods. Logger is faster and allocates less, but supports only structured logging with strongly typed fields.

Is zap faster than the standard library or slog?

The README reports that zap is more performant than comparable structured logging packages and the standard library in its own benchmarks. It also cautions that benchmarks should be taken with a grain of salt, so test with your own workload.

What are good alternatives to zap?

The README compares zap with zerolog, logrus, slog and go-kit. Choose slog if you must stick to the standard library, since zap is a separate dependency with its own API.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Zap suits Go developers running services that log heavily, teams that want structured output, and projects where logging overhead matters. If you only need simple print statements, or you must use only the standard library's log/slog, pick something simpler or use slog instead.

Install options & downloads