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
| Option | What it does |
|---|---|
-d | decode |
-w N | wrap lines every N characters (default 76) |
-w0 | don't wrap at all — the result is a single line with no \n at the end |
-i | when 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:
| Option | Alphabet and where you see it |
|---|---|
--base64 | same as base64 |
--base64url | - and _ instead of + and /: JWT, tokens in URLs and file names |
--base32 | A–Z, 2–7: TOTP secrets, case-insensitive identifiers (there's also a separate base32 command) |
--base16 | hexadecimal 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
echowithout-nadds\n.echo 'hello' | base64givesaGVsbG8K, notaGVsbG8=— the newline got encoded. A password or token with it won't match later. Useecho -norprintf '%s'.- Long output is wrapped. Without
-w0the 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 -don a string with-and_givesinvalid input. For JWTs and tokens from URLs you needbasenc --base64url -d(or atr '_-' '/+'replacement). - No
=at the end. In the URL-safe variant the=padding is often dropped.base64 -dthen outputs the data but printsinvalid inputand returns code1— append=until the length is a multiple of 4. - Spaces and garbage in the input also give
invalid input. The-iflag 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.