How to Encode and Decode Base64

Why you would encode at all

You reach for Base64 when you have binary data that needs to live somewhere text-only: an image embedded in a data URL, credentials in an HTTP header, or a blob inside JSON. The goal is never to hide the data — it is to make it survive a text channel intact. Once you keep that in mind, the commands below are straightforward.

Encoding in the browser

Browsers expose btoa() (binary to ASCII) and atob() (the reverse) on the window object:

btoa('51NAV');    // "NTe5TkFW"
atob('NTe5TkFW'); // "51NAV"

One gotcha: btoa only accepts Latin-1 (single-byte) strings. Hand it "你好" and it throws. For Unicode text, encode to UTF-8 first:

btoa(unescape(encodeURIComponent('你好')));

The reverse is decodeURIComponent(escape(atob(...))). It is clumsy, but it works without pulling in a library.

Encoding in the terminal

On Linux and macOS, base64 is built in:

echo -n "51NAV" | base64          # encode
echo -n "NTe5TkFW" | base64 -d    # decode

base64 image.png > image.b64      # encode a whole file

The -n matters more than it looks: without it, echo appends a newline that becomes part of the encoded output. That trailing newline is the source of countless “why doesn’t my decode match?” bugs.

Encoding in Python

import base64

encoded = base64.b64encode(b"51NAV").decode()
print(encoded)                            # NTe5TkFW
print(base64.b64decode(encoded).decode())  # 51NAV

Note the b"..." — b64encode wants bytes, not a string, so encode your text first. Python also ships base64.urlsafe_b64encode and urlsafe_b64decode for the URL variant, which saves you from doing the character swaps by hand.

Base64URL for tokens and URLs

Standard Base64 uses + and /, which get mangled in URLs and tokens. Base64URL replaces them with - and _ and drops the = padding:

function toBase64Url(str) {
  return btoa(str)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

JWTs use this exact scheme, which is why a token string looks slightly wrong if you expect normal Base64. When you decode a token, do the reverse swap before calling atob.

A quick checklist

• Need to inspect an opaque blob? base64 -d it (after fixing any URL-safe characters).
• Carrying data in a URL or token? Use Base64URL, never plain Base64.
• Remember it is reversible — Base64 is not a way to hide anything.
• Watch for stray newlines from echo and stray padding when you strip it.

Which method should you reach for?

• Browser — when you are already in front-end code and the string is small.
• Terminal — when you are scripting, piping between commands, or processing files.
• Python — when encoding is one step in a larger backend task.

They all produce identical output, so pick whatever is already in your hands. The only real decision is Base64 versus Base64URL, and that is settled by where the result is going: a header or a file wants plain Base64, a URL or token wants Base64URL.

Common mistakes

• Encoding a string without converting to bytes first — this bites people in Python, Go, and Rust.
• Forgetting the newline from echo -n.
• Treating Base64 output as encrypted.
• Leaving = padding on when a downstream parser rejects it — strip it for URLs.

Related

• Understand the basics in What Is Base64?.
• See Base64 inside tokens in What Is a JWT?.