Open-Source Wikis

/

Go

/

Components

/

Standard library

golang/go

Standard library

Most of src/ is the Go standard library — the packages users import as "fmt", "net/http", "crypto/tls", and so on. There are around 200 user-importable packages plus a similar number of internal/... packages used only by the rest of the standard library.

This page is an organizing index, not an API reference. For per-package documentation, run go doc <pkg> or read each package's source.

Purpose

The standard library is the curated set of "everything Go users get without adding a dependency." Inclusion in std is a high bar:

  • The Go 1 compatibility promise applies in full.
  • Public API additions go through the proposal process.
  • Updates ship with each Go release; users cannot upgrade just one package.

The library follows a deliberate batteries-included-but-conservative philosophy: networking, crypto, encoding, OS interaction, and basic data structures are in. Frameworks, ORMs, and high-level abstractions are not.

Top-level groups

src/
├── archive/{tar,zip}/                Archives
├── bufio/                            Buffered I/O
├── builtin/                          Documentation-only stub for builtins
├── bytes/                            []byte helpers
├── cmp/                              Constraint helpers for ordering
├── compress/{flate,gzip,bzip2,lzw,zlib}/  Compression
├── container/{heap,list,ring}/       Generic-ish data structures
├── context/                          context.Context
├── crypto/...                        Crypto: hashing, ciphers, TLS, X.509, RSA, ECDSA, ML-KEM, ...
├── database/sql/                     SQL database abstraction
├── debug/{dwarf,elf,gosym,macho,pe}/ Binary format readers
├── embed/                            //go:embed support
├── encoding/{json,xml,csv,...}       Data formats
├── errors/                           Errors helpers
├── expvar/                           Exposed runtime variables
├── flag/                             Command-line flags
├── fmt/                              Formatted I/O
├── go/{ast,parser,printer,types,...} Public Go AST/types library (separate from compiler internals)
├── hash/{adler32,crc32,crc64,fnv,maphash}/ Hash functions
├── html/, html/template/             HTML escaping + template engine
├── image/{color,draw,gif,jpeg,png,...} Imaging
├── index/suffixarray/                Suffix array
├── io/, io/fs/                       I/O abstraction + file system interface
├── iter/                             range-over-function (Go 1.23+)
├── log/, log/slog/                   Logging
├── maps/, slices/                    Generic map and slice helpers (Go 1.21+)
├── math/, math/big/, math/bits/, math/rand/  Numerics
├── mime/, mime/multipart/, mime/quotedprintable/  MIME
├── net/, net/http/, net/mail, net/netip, net/rpc/, net/smtp/, net/textproto/, net/url/  Networking
├── os/, os/exec/, os/signal/, os/user/  OS interaction
├── path/, path/filepath/             Path handling
├── plugin/                           Loadable Go plugins
├── reflect/                          Reflection
├── regexp/                           RE2-style regexes
├── runtime/...                       The runtime + sub-APIs (debug, pprof, trace, metrics)
├── simd/                             SIMD types/operations (in development)
├── slices/                           Generic slice helpers
├── sort/                             Sorting (mostly superseded by slices.Sort)
├── strconv/                          String <-> numeric
├── strings/                          string helpers
├── structs/                          Struct field helpers
├── sync/, sync/atomic/               Synchronization
├── syscall/                          Raw syscall interface (frozen except for fixes)
├── testing/, testing/{quick,fstest,iotest,synctest,slogtest}/  Test framework
├── text/{scanner,tabwriter,template,template/parse}/  Text processing
├── time/, time/tzdata/               Time
├── unicode/, unicode/utf8, unicode/utf16/  Unicode
├── unique/                           unique.Make for interning
├── unsafe/                           Documentation-only stub
└── weak/                             Weak pointers

The internal/ directory under src/ mirrors many of these with implementation details (e.g., internal/poll underlies os and net, internal/abi is shared low-level type info, internal/testenv is shared by tests).

Package categories

Foundational

These have either no dependencies or only on each other and are imported transitively by almost everything else:

  • unsafe, internal/unsafeheader, internal/abi — low-level layout primitives.
  • runtime, runtime/internal/... — the runtime itself.
  • errors, cmp, iter — small abstractions.
  • internal/byteorder, internal/cpu, internal/goarch, internal/goos — build/runtime metadata.

I/O and OS

  • io, io/fs — interfaces.
  • os, os/exec, os/signal, os/user — OS primitives.
  • internal/poll — the I/O multiplexer underlying net and os.
  • syscall (frozen) and internal/syscall/... — raw syscall surface.

Networking

  • net — TCP/UDP/Unix sockets, DNS resolution.
  • net/http — HTTP/1.1 server + client. HTTP/2 lives under net/http/internal/http2/.
  • net/url, net/textproto, net/mail, net/smtp, net/rpc, net/netip — supporting protocols.

Encoding / data formats

  • encoding/json, encoding/xml, encoding/csv, encoding/binary, encoding/gob, encoding/hex, encoding/base64, encoding/base32, encoding/asn1.
  • A new encoding/json/v2 and encoding/json/jsontext are being staged in for a future major release.

Crypto

  • crypto, crypto/aes, crypto/cipher, crypto/des, crypto/dsa, crypto/ecdh, crypto/ecdsa, crypto/ed25519, crypto/elliptic, crypto/hkdf, crypto/hmac, crypto/md5, crypto/mlkem, crypto/pbkdf2, crypto/rand, crypto/rc4, crypto/rsa, crypto/sha1, crypto/sha256, crypto/sha3, crypto/sha512, crypto/subtle, crypto/x509.
  • crypto/tls — TLS 1.0 through TLS 1.3 client and server.
  • crypto/internal/... — implementation, including FIPS-140 boundaries (crypto/internal/fips140).

Text and formatting

  • fmt, strings, strconv, bytes, bufio.
  • text/template, text/scanner, text/tabwriter.
  • regexp, regexp/syntax — RE2 implementation.
  • unicode, unicode/utf8, unicode/utf16.

Compilation / static analysis (the go/* packages)

These mirror parts of the compiler but are intentionally separate:

  • go/ast, go/parser, go/printer, go/format.
  • go/types — public type checker (the compiler internally uses cmd/compile/internal/types2, a fork of this).
  • go/token, go/scanner.
  • go/build — the legacy package loader, still used by some tools.

Concurrency

  • sync, sync/atomic — primitives.
  • context — cancellation and deadlines.
  • runtime/trace, runtime/pprof — instrumentation.

Testing

  • testing — the standard test framework.
  • testing/quick — property-based testing.
  • testing/fstest, testing/iotest, testing/synctest, testing/slogtest — specialized helpers.

Time

  • time, time/tzdata — clocks, timers, time zones.

Tight coupling with the runtime

A handful of packages are unusually tied to runtime:

  • sync — Mutex, RWMutex, WaitGroup, Cond, Once use semaphores in the runtime via //go:linkname.
  • reflect — uses runtime type metadata directly; reflect.Value tracks heap pointers in coordination with the GC.
  • os — many file operations route through internal/poll and the runtime network poller.
  • time — timer wheel is in the runtime; time.After, time.Timer are thin wrappers.
  • runtime/pprof, runtime/trace, runtime/metrics, runtime/debug — public wrappers on runtime internals.

When you change anything in runtime that involves linkname, expect to also touch the consuming standard library package.

Build constraints

Standard library packages use build tags heavily, especially in os, net, crypto, and runtime. Common patterns:

  • *_unix.go — POSIX-y systems (Linux, BSD, macOS, Solaris, Plan 9-ish).
  • *_linux.go, *_darwin.go, *_windows.go, *_plan9.go — per-OS.
  • *_amd64.go, *_arm64.go, *_riscv64.go — per-arch.
  • *_test.go always; *_internal_test.go for tests inside the package; *_external_test.go for the corresponding external test package.

How packages move between standard library and golang.org/x/...

Many features start in the golang.org/x/... "experimental" repos before promotion:

  • slog started in golang.org/x/exp/slog, joined the standard library as log/slog in Go 1.21.
  • maps, slices started in golang.org/x/exp/{maps,slices} then joined as maps, slices in Go 1.21.
  • iter, unique, weak, synctest, simd, mlkem are recent additions.
  • Older packages occasionally move the other way: parts of crypto/... are deprecated and replaced by newer APIs.

API compatibility surfaces

api/ at the repo root contains the declared API of every Go release. Files like api/go1.txt, api/go1.21.txt, api/next/<issue>.txt track every public symbol. The cmd/api tool (src/cmd/api/) compares a candidate build to those manifests during CI.

Vendor directory

src/vendor/ and src/cmd/vendor/ hold the small set of golang.org/x/... packages that the standard library and toolchain depend on. They're vendored to avoid a dependency cycle on themselves. Updates happen via go mod vendor from the appropriate go.mod (src/go.mod for the library, src/cmd/go.mod for the toolchain). See src/README.vendor and src/cmd/README.vendor.

  • Compiler — note the parallel go/* (public) vs. cmd/compile/internal/types2 (internal) split.
  • Runtime — the packages most coupled to runtime internals.
  • Reference → dependencies — what's in src/vendor/ and why.
  • api/ directory — every public symbol of every Go release.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.

Standard library – Go wiki | Factory