go doc - Terminal Documentation Viewer

go doc prints documentation for Go packages, functions, types, and methods directly in your terminal. It reads the same doc comments you write in your source code, so you don't need a web browser, a separate server, or an internet connection to look up how a standard‑library function works.

What go doc Does

When you run go doc with a package name or symbol, it searches your local Go installation and module cache for that package’s source code. It extracts the package‑level comment and the documentation comment attached to the requested symbol, formats them, and prints them to standard output.

If you run go doc with no arguments inside a package directory, it shows the documentation for that package.

Why a Terminal‑First Documentation Tool Matters

Before go doc, reading Go documentation often meant opening a browser and visiting pkg.go.dev or running the godoc server. Both work, but they break your flow when you’re deep inside a terminal session. With go doc, you can check a function signature, read a package’s overview, or verify what a method does in a couple of keystrokes — without ever leaving your editor or command line.

This is especially useful when you’re working in an environment with limited or no internet access, such as a build container, an air‑gapped machine, or a slow connection.

Viewing Documentation for the Current Package

If you’re inside a directory that contains Go source files and you just want to see the package’s overview, run go doc with no arguments:

cd myproject
go doc

This prints the package comment (the block of text immediately before the package declaration) and lists all exported symbols — functions, types, variables, and constants — with their one‑line summaries. The output mirrors the top‑level documentation you’d see on pkg.go.dev, but it’s generated locally.

Looking Up a Specific Package

To view documentation for a package in the standard library, pass its import path:

go doc fmt

The output begins with the package declaration and import path, followed by the full package comment, then a list of all exported symbols with their signatures. Here’s a trimmed example:

package fmt // import "fmt"
Package fmt implements formatted I/O with functions analogous
to C's printf and scanf. The format 'verbs' are derived from C's
but are simpler.
func Errorf(format string, a ...any) error
func Fprint(w io.Writer, a ...any) (n int, err error)
func Fprintf(w io.Writer, format string, a ...any) (n int, err error)
func Fprintln(w io.Writer, a ...any) (n int, err error)
...

This single command replaces a web search when you need a quick reminder of what fmt offers. You can also pass a full module path for a dependency that’s already in your module cache:

go doc github.com/gorilla/mux

If the package isn’t in the cache, go doc will return an error. You’d need to add it to your module with go get first.

Looking Up a Specific Symbol

To see the full documentation for a function, type, or method, append a dot and the symbol name:

go doc fmt.Println

The output focuses on just that symbol:

package fmt // import "fmt"
func Println(a ...any) (n int, err error)
    Println formats using the default formats for its operands and writes to
    standard output. Spaces are always added between operands and a newline
    is appended. It returns the number of bytes written and any write error
    encountered.

This is the fastest way to check a function signature and read its documented behavior while you’re writing code.

Types and Their Methods

For a type, go doc prints the type’s definition and its doc comment, along with a list of its exported methods. To zoom into a specific method, use Type.Method:

go doc net/http.Client
go doc net/http.Client.Do

The first command shows the Client struct and all its methods; the second shows only the Do method’s documentation.

If a type embeds another type, you can access the embedded type’s methods through the outer type as long as the method is promoted. go doc follows the same promotion rules the compiler does.

Flags That Change Output

Four flags control how go doc searches and what it displays. They’re especially useful when you’re debugging a package or exploring its internals.

Showing Unexported Symbols: -u

By default, go doc shows only exported identifiers — those starting with an uppercase letter. The -u flag includes unexported functions, types, methods, and fields.

go doc -u mypackage

Viewing Source Code: -src

The -src flag prints the full source code of the requested symbol — doc comment, declaration, and body — rather than the formatted documentation.

go doc -src fmt.Println

This is useful when the doc comment doesn’t answer your question and you need to see the implementation, or when you want to verify how a standard‑library function handles edge cases.

Case‑Sensitive Matching: -c

Go allows exported identifiers that differ only in case (e.g., New and new). The -c flag tells go doc to respect the exact case you typed instead of performing a case‑insensitive match.

go doc -c unicode/utf8.DecodeRune

Without -c, the command might match a different symbol if one exists. With -c, you get an error if the precise case doesn’t exist.

Treating main Packages as Regular Packages: -cmd

Packages declared package main are normally treated as commands. Their exported symbols are hidden from the top‑level package documentation because end users rarely interact with them directly. When you’re developing a command, you may want to see those symbols. The -cmd flag exposes them:

go doc -cmd mycmd

This is useful inside a project that defines multiple commands in a single module and you need to cross‑reference shared utilities.

How Beginners Should Think About go doc

Think of go doc as a local, text‑only version of pkg.go.dev. It’s not a learning tool that explains concepts from scratch — it displays the same doc comments that the package author wrote. If those comments are well‑written, go doc becomes a quick, reliable reference. If they’re sparse, go doc still gives you the exact function signatures, which is often enough to understand what arguments a function expects.

You don’t need to memorize every flag. Start with go doc <package>.<symbol> and the output will immediately show you the signature and the author’s explanation. That single pattern covers most day‑to‑day usage.

Common Mistakes When Using go doc

A second common mistake is assuming go doc can look up any package on the internet. It cannot. The package’s source must already exist on your machine — either in the standard library, in the module cache, or in a directory inside your GOPATH. If you get an error that the package cannot be found, you likely need to add it as a dependency or download it with go get.

Another pitfall: running go doc from outside a module and expecting it to resolve a package from a remote repository. Without a go.mod file to guide dependency resolution, go doc can only search the standard library and your local workspace. Set up a module first if you need to document third‑party code.

go doc and godoc Are Different Tools

Older Go documentation often references godoc. That tool generates HTML documentation and can run a local web server. The godoc binary is not installed by default in recent Go releases; go doc has replaced it for terminal‑based documentation lookups.

go doc is simpler, faster for quick lookups, and integrated directly into the go command. Use godoc if you need to generate static HTML files or run a documentation server for an internal package repository, but reach for go doc when you just need to read a comment in your terminal.

Integrating go doc Into Your Workflow

Beyond one‑off lookups, go doc fits into a few productive patterns:

• During code review: When you encounter an unfamiliar function, go doc <pkg>.<Func> lets you verify its contract without context‑switching.
• In shell scripts and CI: You can parse the output of go doc to check whether a certain symbol exists or to extract its signature, though the output format is meant for humans and may change between Go versions. For programmatic needs, use go doc -src or the go/build package.
• With editor integration: Many editors can run go doc and display the result in a pop‑up. Check whether your editor’s Go plugin supports a “Show Documentation” command.

The key benefit is speed: you stay in the same terminal, your fingers stay on the keyboard, and you get the answer in seconds.

Summary

go doc solves a specific, common problem — “What does this function do, and what arguments does it take?” — without pulling you out of the terminal. It works entirely offline, respects the same doc comments that drive pkg.go.dev, and requires no setup beyond having Go installed.

The habit worth building: whenever you type a function name you don’t fully remember, run go doc on it. You’ll reinforce your mental model of the standard library and third‑party packages, and you’ll catch subtle details (like which errors a function can return) that are easy to miss when skimming code alone.