Base64 Encode and Decode — What It Is and How to Use It

Every developer eventually runs into Base64. Maybe you are staring at a long string of letters and numbers in an API response and wondering what it means. Maybe you need to embed an image inside a JSON payload. Maybe you are debugging an email that arrived as a wall of seemingly random characters.

Base64 is one of those things that is everywhere but rarely explained well. Most people learn just enough to call btoa() and move on. That works until it does not — until you hit a Unicode string that breaks, or you need to understand why your encoded payload is 33 percent larger than the original, or you are asked in a code review why you chose Base64 instead of hex encoding.

This post covers all of it. What Base64 actually is, how the algorithm works step by step, when you should use it, when you should not, and practical code examples in JavaScript, Python, and the command line.

What Is Base64 Encoding#

Base64 is a binary-to-text encoding scheme. It takes arbitrary binary data — bytes that could represent anything from a JPEG image to a cryptographic key — and converts it into a string of printable ASCII characters.

The name comes from the fact that it uses 64 characters to represent data. Those 64 characters are:

• A through Z (26 characters)
• a through z (26 characters)
• 0 through 9 (10 characters)
• + and / (2 characters)

There is also =, which is used as a padding character. More on that later.

The key thing to understand: Base64 is not encryption. It does not protect data. Anyone can decode a Base64 string. It is a transport encoding — a way to represent binary data in contexts that only support text.

Why Base64 Exists#

The internet was originally built around text. Protocols like SMTP (email), HTTP headers, and early versions of HTML were designed to handle ASCII text, not raw binary data. Try sending a JPEG file through a protocol that expects printable characters and you will get corruption. Some bytes in a JPEG happen to be control characters, null bytes, or values above 127 that older systems do not handle correctly.

Base64 solves this by mapping every possible byte sequence to safe, printable ASCII characters. The tradeoff is size: Base64-encoded data is about 33 percent larger than the original, because you are representing 6 bits of data with each character instead of 8.

That 33 percent overhead matters. It is why you should not Base64-encode an entire video file and stick it in a JSON response. But for small payloads — authentication tokens, inline images in CSS, embedded files in API calls — the convenience outweighs the cost.

How the Base64 Algorithm Works#

Understanding the algorithm makes everything else click. Here is the step-by-step process.

Step 1: Convert Input to Binary#

Take your input string and get its binary representation. Each ASCII character is one byte (8 bits).

For the string Man:

M = 77  = 01001101
a = 97  = 01100001
n = 110 = 01101110

Concatenate the bits: 010011010110000101101110

Step 2: Split into 6-Bit Groups#

Base64 uses 6-bit groups instead of 8-bit bytes. Why 6? Because 2 to the power of 6 equals 64, which gives us exactly 64 possible values — one for each character in the Base64 alphabet.

Split the 24 bits into groups of 6:

010011 010110 000101 101110

Step 3: Map to Base64 Characters#

Each 6-bit group is a number between 0 and 63. Look up that number in the Base64 index table:

010011 = 19 = T
010110 = 22 = W
000101 = 5  = F
101110 = 46 = u

So Man encodes to TWFu.

How Padding Works#

The algorithm processes 3 bytes at a time (24 bits, which splits evenly into four 6-bit groups). But input is not always a multiple of 3 bytes.

When the input length is not divisible by 3, the algorithm pads with zero bits and adds = characters to signal how many bytes were padded.

For the string Ma (2 bytes, 16 bits):

M = 01001101
a = 01100001

Concatenated: 0100110101100001

We need 18 bits (three 6-bit groups), so pad with two zero bits:

010011 010110 000100

That gives us TWE. Since we had one byte of padding, we append one = sign: TWE=.

For a single character M (1 byte, 8 bits):

M = 01001101

We need 12 bits (two 6-bit groups), so pad with four zero bits:

010011 010000

That gives us TQ. Since we had two bytes of padding, we append two = signs: TQ==.

The rule is simple:

• 0 bytes of padding: no =
• 1 byte of padding: one =
• 2 bytes of padding: two =

You will never see three = signs because the cycle repeats every 3 bytes.

The Full Base64 Index Table#

For reference, here is the complete mapping:

Value  Char    Value  Char    Value  Char    Value  Char
0      A       16     Q       32     g       48     w
1      B       17     R       33     h       49     x
2      C       18     S       34     i       50     y
3      D       19     T       35     j       51     z
4      E       20     U       36     k       52     0
5      F       21     V       37     l       53     1
6      G       22     W       38     m       54     2
7      H       23     X       39     n       55     3
8      I       24     Y       40     o       56     4
9      J       25     Z       41     p       57     5
10     K       26     a       42     q       58     6
11     L       27     b       43     r       59     7
12     M       28     c       44     s       60     8
13     N       29     d       45     t       61     9
14     O       30     e       46     u       62     +
15     P       31     f       47     v       63     /

Base64 Variants You Should Know About#

The standard Base64 alphabet uses + and /. These characters have special meaning in URLs and file systems, which causes problems. Several variants exist to address this.

Base64url#

Defined in RFC 4648, Base64url replaces + with - and / with _. It also typically omits padding (=). This is the variant used in JWTs, data URIs in some contexts, and anywhere Base64 data appears in a URL.

MIME Base64#

Used in email (MIME), this variant inserts line breaks every 76 characters. The actual character set is the same as standard Base64, but the line wrapping means you cannot compare MIME-encoded strings directly without stripping whitespace first.

Encoding and Decoding in JavaScript#

JavaScript has built-in functions for Base64, but they have a well-known limitation with Unicode.

The Basic Functions#

// Encode
const encoded = btoa("Hello, World!");
console.log(encoded); // "SGVsbG8sIFdvcmxkIQ=="
 
// Decode
const decoded = atob("SGVsbG8sIFdvcmxkIQ==");
console.log(decoded); // "Hello, World!"

The Unicode Problem#

Try encoding a string with non-ASCII characters and btoa throws an error:

btoa("Hello, "); // DOMException: The string contains characters outside of the Latin1 range

The fix is to encode the string as UTF-8 first, then Base64-encode the bytes:

// Encode Unicode to Base64
function encodeBase64(str) {
  const bytes = new TextEncoder().encode(str);
  const binary = Array.from(bytes, (byte) => String.fromCodePoint(byte)).join("");
  return btoa(binary);
}
 
// Decode Base64 to Unicode
function decodeBase64(base64) {
  const binary = atob(base64);
  const bytes = Uint8Array.from(binary, (char) => char.codePointAt(0));
  return new TextDecoder().decode(bytes);
}
 
console.log(encodeBase64("Hello, "));    // "SGVsbG8sIPCfjI0="
console.log(decodeBase64("SGVsbG8sIPCfjI0=")); // "Hello, "

Node.js Buffer Approach#

In Node.js, the Buffer class handles this more cleanly:

// Encode
const encoded = Buffer.from("Hello, World!", "utf-8").toString("base64");
console.log(encoded); // "SGVsbG8sIFdvcmxkIQ=="
 
// Decode
const decoded = Buffer.from("SGVsbG8sIFdvcmxkIQ==", "base64").toString("utf-8");
console.log(decoded); // "Hello, World!"
 
// Base64url variant
const urlSafe = Buffer.from("Hello, World!", "utf-8").toString("base64url");
console.log(urlSafe); // "SGVsbG8sIFdvcmxkIQ"

Encoding and Decoding in Python#

Python makes Base64 handling straightforward with the base64 module.

import base64
 
# Encode a string
text = "Hello, World!"
encoded = base64.b64encode(text.encode("utf-8"))
print(encoded)  # b'SGVsbG8sIFdvcmxkIQ=='
 
# Decode back to string
decoded = base64.b64decode(encoded).decode("utf-8")
print(decoded)  # "Hello, World!"
 
# Base64url variant
url_encoded = base64.urlsafe_b64encode(text.encode("utf-8"))
print(url_encoded)  # b'SGVsbG8sIFdvcmxkIQ=='
 
# Encode a file
with open("image.png", "rb") as f:
    file_encoded = base64.b64encode(f.read())
    print(file_encoded[:50])  # First 50 chars of the encoded file

Python also handles Unicode naturally since you explicitly encode to bytes before Base64 encoding:

import base64
 
text = "Merhaba Dunya"
encoded = base64.b64encode(text.encode("utf-8"))
print(encoded)  # b'TWVyaGFiYSBEdW55YQ=='
 
decoded = base64.b64decode(encoded).decode("utf-8")
print(decoded)  # "Merhaba Dunya"

Encoding and Decoding from the Command Line#

Linux and macOS#

The base64 command is available on most Unix systems:

# Encode a string
echo -n "Hello, World!" | base64
# SGVsbG8sIFdvcmxkIQ==
 
# Decode a string
echo "SGVsbG8sIFdvcmxkIQ==" | base64 --decode
# Hello, World!
 
# Encode a file
base64 image.png > image_encoded.txt
 
# Decode a file
base64 --decode image_encoded.txt > image_decoded.png

The -n flag on echo is important. Without it, echo appends a newline character, and that newline gets encoded too.

Using OpenSSL#

OpenSSL provides another way to handle Base64 from the terminal:

# Encode
echo -n "Hello, World!" | openssl base64
# SGVsbG8sIFdvcmxkIQ==
 
# Decode
echo "SGVsbG8sIFdvcmxkIQ==" | openssl base64 -d
# Hello, World!

PowerShell on Windows#

# Encode
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("Hello, World!"))
# SGVsbG8sIFdvcmxkIQ==
 
# Decode
[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("SGVsbG8sIFdvcmxkIQ=="))
# Hello, World!

When to Use Base64#

Base64 is the right choice in several specific scenarios.

Embedding Binary Data in JSON or XML#

JSON does not support binary data natively. If you need to include an image, PDF, or any binary file in a JSON payload, Base64 is the standard approach:

{
  "filename": "document.pdf",
  "content": "JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZw...",
  "contentType": "application/pdf"
}

Data URIs in HTML and CSS#

You can embed small images directly in HTML or CSS using data URIs:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." alt="icon" />

.icon {
  background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxu...");
}

This eliminates an HTTP request for small assets. For icons under a few kilobytes, the reduced latency often outweighs the size overhead.

Email Attachments#

MIME encoding uses Base64 to attach binary files to emails. When you attach a PDF to an email, your mail client Base64-encodes it behind the scenes.

Authentication Headers#

HTTP Basic Authentication Base64-encodes the username:password pair:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Note: this is encoding, not encryption. The credentials are trivially decodable. Always use HTTPS when sending Basic Auth headers.

Storing Binary Data in Text-Only Databases#

Some legacy systems or configurations only support text fields. Base64 lets you store binary data in those fields, though a proper binary column is always preferable when available.

When Not to Use Base64#

Large Files#

The 33 percent size overhead adds up fast. A 10 MB file becomes roughly 13.3 MB after Base64 encoding. For large files, use multipart form uploads or binary protocols instead.

Encryption or Security#

Base64 is not a security mechanism. Encoding credentials in Base64 does not protect them. If you see someone describing Base64 as "encrypted," correct them. Use actual encryption (AES, RSA, or a higher-level library like libsodium) for sensitive data.

Obfuscation#

Some developers Base64-encode strings to hide them from casual inspection. This is security through obscurity and provides zero protection. Any developer can decode it in seconds.

URL Parameters (Without Base64url)#

Standard Base64 contains +, /, and =, all of which have special meaning in URLs. If you must put Base64 data in a URL, use the Base64url variant or properly URL-encode the string.

Common Pitfalls and Debugging Tips#

Whitespace in Encoded Strings#

MIME-encoded Base64 includes line breaks every 76 characters. If you copy a Base64 string from an email source and try to decode it, strip the whitespace first:

const clean = encodedString.replace(/\s/g, "");
const decoded = atob(clean);

Incorrect Padding#

Some implementations omit padding (=). Most decoders handle this gracefully, but if you get errors, try adding padding:

function addPadding(base64) {
  const remainder = base64.length % 4;
  if (remainder === 2) return base64 + "==";
  if (remainder === 3) return base64 + "=";
  return base64;
}

Double Encoding#

A surprisingly common bug: encoding data that is already Base64-encoded. If you see output like U0dWc2JHOHNJRmR2Y21sa0lR, you might be looking at double-encoded data. Decode it twice.

Character Encoding Mismatches#

If you encode a string as UTF-8 on one system and decode it as Latin-1 on another, you will get garbled output. Always agree on the character encoding (UTF-8 is the safe default) before Base64 encoding.

Base64 in JWTs#

JSON Web Tokens use Base64url encoding (not standard Base64) for their header and payload segments. A JWT looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Each segment between dots is Base64url-encoded JSON. You can decode the payload to inspect claims without verifying the signature:

function decodeJwtPayload(token) {
  const payload = token.split(".")[1];
  const padded = payload.replace(/-/g, "+").replace(/_/g, "/");
  return JSON.parse(atob(padded));
}
 
const claims = decodeJwtPayload("eyJhbGciOiJIUzI1NiIs...");
console.log(claims);
// { sub: "1234567890", name: "John Doe", iat: 1516239022 }

This is useful for debugging, but never trust decoded JWT claims without verifying the signature server-side.

Performance Considerations#

Base64 encoding and decoding is fast. On modern hardware, you can encode hundreds of megabytes per second. The bottleneck is almost never the encoding itself — it is the increased data size.

In a web context, the 33 percent overhead matters most for:

• Network transfer: More bytes means longer transfer times, especially on slow connections.
• Memory usage: The encoded string takes 33 percent more RAM than the original binary data.
• Cache efficiency: Larger payloads mean fewer items fit in cache.

For most use cases — API tokens, small embedded images, configuration values — the overhead is negligible. For anything over a few hundred kilobytes, consider whether Base64 is really the right tool.

Encode and Decode Base64 Online#

If you need a quick way to encode or decode Base64 strings without writing code, you can use the free Base64 Encoder and Decoder tool on akousa.net. It runs entirely in your browser — nothing is sent to a server — so it is safe for sensitive data like API keys or tokens. It handles Unicode correctly and supports both standard Base64 and the Base64url variant.

Summary#

Base64 is a simple, well-defined encoding that converts binary data to printable ASCII text. It is not encryption, not compression, and not obfuscation. It is a transport encoding that solves a real problem: getting binary data through text-only channels.

The algorithm groups input bytes into 6-bit chunks and maps each chunk to one of 64 printable characters. The output is always 33 percent larger than the input. Padding with = handles inputs that are not a multiple of 3 bytes.

Use it for embedding binary data in JSON, data URIs, email attachments, and authentication headers. Do not use it for large files, security, or anything where the size overhead matters. Always use the Base64url variant when putting encoded data in URLs or JWTs.

Every major language has built-in Base64 support. In JavaScript, watch out for the Unicode limitation of btoa and atob. In Python, remember to encode strings to bytes first. On the command line, remember the -n flag with echo to avoid encoding a trailing newline.

Base64 is one of those tools that rewards understanding. Once you know how it works, you stop treating it as a black box and start making better decisions about when and how to use it.