← Full reference

base64

Base64 encoding and decoding — -d, -w0, the URL-safe variant, common newline mistakes

base64 turns any bytes into text made of 64 safe characters (A–Z, a–z, 0–9, +, /) and back. That's how binary data is passed where text is expected: HTTP headers, JSON, Kubernetes secrets, data URIs, email attachments.

Syntax

base64 [options] [file]       # encode
base64 -d [options] [file]    # decode

Without a file (or with -) it reads stdin and writes the result to stdout.

Options

OptionWhat it does
-ddecode
-w Nwrap lines every N characters (default 76)
-w0don't wrap at all — the result is a single line with no \n at the end
-iwhen decoding, skip characters outside the alphabet (spaces, garbage)

What the output looks like

Every 3 input bytes become 4 characters, so encoded data is a third longer than the original. If the input length isn't divisible by 3, padding is added at the end: = or ==. Example: hello (5 bytes) → aGVsbG8= (8 characters).

Related encodings: basenc

basenc from coreutils supports several variants; its -d, -w, -i options are the same:

OptionAlphabet and where you see it
--base64same as base64
--base64url- and _ instead of + and /: JWT, tokens in URLs and file names
--base32A–Z, 2–7: TOTP secrets, case-insensitive identifiers (there's also a separate base32 command)
--base16hexadecimal notation of bytes in upper case

Base64 is encoding, not encryption: anyone can decode it with a single command.

Examples

# encode a string; -n so the newline isn't encoded
echo -n 'hello' | base64
# aGVsbG8=

# decode
echo 'aGVsbG8=' | base64 -d

# a file as a single line — for JSON, YAML, variables
base64 -w0 image.png > image.b64

# and back to a binary file
base64 -d image.b64 > image.png

# make sure the file is unchanged after encoding and decoding
base64 image.png | base64 -d | cmp - image.png && echo 'identical'

# a Basic auth header by hand
echo -n 'admin:secret' | base64

# URL-safe Base64 (JWT, tokens in URLs)
echo -n 'hello?' | basenc --base64url
echo 'aGVsbG8_' | basenc --base64url -d

# decode the middle of a JWT — the payload (the second part between the dots)
echo "$TOKEN" | cut -d. -f2 | basenc --base64url -d 2>/dev/null

# base32 and hex view
echo -n 'hi' | base32
echo -n 'hi' | basenc --base16

# same with openssl
echo -n 'hello' | openssl base64

Pitfalls

  • echo without -n adds \n. echo 'hello' | base64 gives aGVsbG8K, not aGVsbG8= — the newline got encoded. A password or token with it won't match later. Use echo -n or printf '%s'.
  • Long output is wrapped. Without -w0 the result is split into 76-character lines. Pasted into YAML, JSON or an HTTP header, such a string keeps the line breaks and breaks things.
  • URL-safe is a different alphabet. Plain base64 -d on a string with - and _ gives invalid input. For JWTs and tokens from URLs you need basenc --base64url -d (or a tr '_-' '/+' replacement).
  • No = at the end. In the URL-safe variant the = padding is often dropped. base64 -d then outputs the data but prints invalid input and returns code 1 — append = until the length is a multiple of 4.
  • Spaces and garbage in the input also give invalid input. The -i flag skips characters outside the alphabet.
  • Double encoding. Values in Kubernetes secrets are already Base64; encode them again and you get a string that decodes to something other than you expect.
  • Don't print a decoded binary file to the terminal — redirect it to a file or look at it with xxd / od -c.

See also

openssl · checksums · curl · kubectl · tr