Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Encoding and Data Formats

The Go encoding/base64 package

Reference for Go's encoding/base64 package: StdEncoding, URLEncoding, Raw variants without padding, streaming encoders, decode errors and sizing helpers.

Base64 turns arbitrary bytes into text made of 64 safe characters, so binary data can travel through JSON, URLs, headers and e-mail. The encoding/base64 package provides the standard alphabet, the URL-safe alphabet, and padded and unpadded forms of each.

You pick an *Encoding value and call methods on it. There are four ready-made ones, and NewEncoding builds a custom alphabet. Base64 is an encoding, not encryption: anyone can reverse it.

Go
s := base64.StdEncoding.EncodeToString([]byte("hello")) // "aGVsbG8="

Try it

Go The four encodings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Decoding errors and streaming

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
var StdEncoding, URLEncoding, RawStdEncoding, RawURLEncoding *Encoding

func NewEncoding(encoder string) *Encoding
func (enc Encoding) WithPadding(padding rune) *Encoding
func (enc *Encoding) EncodeToString(src []byte) string
func (enc *Encoding) DecodeString(s string) ([]byte, error)
func (enc *Encoding) Encode(dst, src []byte)
func (enc *Encoding) Decode(dst, src []byte) (n int, err error)
func (enc *Encoding) AppendEncode(dst, src []byte) []byte
func (enc *Encoding) AppendDecode(dst, src []byte) ([]byte, error)
func (enc *Encoding) EncodedLen(n int) int
func (enc *Encoding) DecodedLen(n int) int
func NewEncoder(enc *Encoding, w io.Writer) io.WriteCloser
func NewDecoder(enc *Encoding, r io.Reader) io.Reader
Encoding Alphabet Padding
StdEncoding A-Z a-z 0-9 + / =
URLEncoding A-Z a-z 0-9 - _ =
RawStdEncoding same as StdEncoding none
RawURLEncoding same as URLEncoding none

Errors and edge cases:

  • Invalid characters or wrong padding produce a base64.CorruptInputError, an int64 holding the byte offset of the problem.
  • A padded encoding rejects input with missing =, and a raw encoding rejects input that has =.
  • \r and \n are ignored while decoding; all other characters outside the alphabet are errors.
  • Decode and Encode write into dst, which must be large enough (EncodedLen, DecodedLen). DecodedLen is an upper bound, so use the returned n.
  • AppendEncode and AppendDecode need Go 1.22.

Usage notes

  • Use the URL variants for URLs, file names and JWTs. + and / have special meaning in URLs. JWT segments use RawURLEncoding.
  • Padded length is 4 * ceil(n / 3); unpadded length is ceil(n * 8 / 6).
  • Always close a streaming encoder. Without Close, the last one or two bytes are never written.
  • JSON: encoding/json already encodes []byte fields as standard base64 strings, so you rarely call this package yourself for that.
  • Not a secret. Base64 hides nothing. Never store passwords or tokens "protected" with it.
  • Other bases: encoding/hex handles hexadecimal, and encoding/base32 follows the same API.