Base64 decoding looks simple.
You take a string like this:
SGVsbG8gV29ybGQ=
Decode it, and get:
Hello World
But in real projects, Base64 decoding can fail for many reasons:
- missing padding
- invalid characters
- Unicode problems
- Base64URL format
- binary data being treated as text
- image data missing a MIME type
- whitespace copied into the string
This guide explains how to decode Base64 safely in JavaScript, Python, and the command line, and how to troubleshoot the most common Base64 decoding issues.
You can also test strings quickly with DecodingBase64, a free client-side Base64 decoder that converts Base64 to text, images, hex output, or downloadable files.
What does Base64 decoding do?
Base64 decoding reverses Base64 encoding.
Base64 represents bytes using readable characters. Decoding converts those characters back into the original bytes.
Those bytes may represent:
- plain text
- JSON
- an image
- a PDF
- a ZIP file
- binary data
- an API token
- a data URI
This is important:
Base64 decoding does not always produce readable text.
Sometimes the decoded output is binary data.
That is why a good decoder should support text, image, file, and hex output.
Basic Base64 decoding in JavaScript
JavaScript provides atob().
const base64 = "SGVsbG8gV29ybGQ=";
const decoded = atob(base64);
console.log(decoded);
// Hello World
This works for simple ASCII text.
But it can break or produce incorrect output with Unicode text.
Unicode-safe Base64 decoding in JavaScript
If the original text contained Unicode characters, you should decode bytes using TextDecoder.
function decodeBase64Unicode(base64) {
const binary = atob(base64);
const bytes = Uint8Array.from(binary, (char) => {
return char.charCodeAt(0);
});
return new TextDecoder("utf-8").decode(bytes);
}
console.log(decodeBase64Unicode("Q2Fmw6kg8J+agA=="));
// Café 🚀
This approach is safer for real-world text because it handles UTF-8 correctly.
Decode Base64 in Python
Python has a built-in base64 module.
import base64
encoded = "SGVsbG8gV29ybGQ="
decoded_bytes = base64.b64decode(encoded)
decoded_text = decoded_bytes.decode("utf-8")
print(decoded_text)
# Hello World
For Unicode text:
import base64
encoded = "Q2Fmw6kg8J+agA=="
decoded = base64.b64decode(encoded).decode("utf-8")
print(decoded)
# Café 🚀
If the output is binary, do not decode it as text. Save it as bytes instead.
Decode Base64 from the command line
On macOS and Linux:
echo "SGVsbG8gV29ybGQ=" | base64 --decode
Output:
Hello World
To decode a Base64 file into a binary file:
base64 --decode input.txt > output.bin
For an image:
base64 --decode image-base64.txt > image.png
The correct output extension depends on the original file type.
How to decode a Base64 image
A Base64 image often looks like this:
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
This is called a data URI.
It has two important parts:
data:image/png;base64,
and then the Base64 data:
iVBORw0KGgoAAAANSUhEUgAA...
The MIME type tells the browser what kind of file it is:
image/png
image/jpeg
image/webp
image/gif
image/svg+xml
If you only have the raw Base64 string, you may need to know the original MIME type to display or save it correctly.
For image debugging, DecodingBase64’s Base64 to Image tool can turn a Base64 image string back into a preview and downloadable image file.
Base64URL decoding
Some strings are not standard Base64. They are Base64URL.
Base64URL is common in:
- JWTs
- URL tokens
- authentication systems
- web-safe identifiers
Standard Base64 uses:
+
/
=
Base64URL may use:
-
_
and often removes padding.
To decode Base64URL in JavaScript, normalize it first:
function base64UrlToBase64(base64Url) {
let base64 = base64Url
.replace(/-/g, "+")
.replace(/_/g, "/");
while (base64.length % 4 !== 0) {
base64 += "=";
}
return base64;
}
function decodeBase64Url(base64Url) {
const base64 = base64UrlToBase64(base64Url);
return atob(base64);
}
console.log(decodeBase64Url("SGVsbG8gV29ybGQ"));
// Hello World
If a standard decoder fails, check whether your string is actually Base64URL.
Common Base64 decoding errors
1. Incorrect padding
Base64 strings often end with:
=
or:
==
Padding helps make the length valid.
If padding is missing, some decoders fail.
Fix:
function addBase64Padding(base64) {
while (base64.length % 4 !== 0) {
base64 += "=";
}
return base64;
}
2. Invalid characters
Standard Base64 should usually contain:
A-Z
a-z
0-9
+
/
=
If you see - and _, it may be Base64URL.
If you see spaces, quotes, commas, or copied line breaks, clean the input first.
3. Whitespace problems
Copied Base64 strings may contain line breaks or spaces.
const cleaned = input.replace(/\s/g, "");
4. Decoding binary as text
Not all decoded Base64 is readable.
If the decoded bytes represent an image or file, showing them as text will look broken.
Use a file output, image preview, or hex view instead.
5. Wrong character set
If the decoded text looks strange, it may be a charset issue.
Try UTF-8 first. If that fails, the original data may use another encoding.
Quick answer
To decode Base64 safely:
- Clean whitespace.
- Detect whether it is standard Base64 or Base64URL.
- Add missing padding if needed.
- Decode to bytes.
- Interpret the bytes correctly as text, image, file, or binary data.
Do not assume every Base64 string is plain text.
Is Base64 secure?
No.
Base64 is not encryption.
Anyone can decode it.
For example:
YXBpX2tleV8xMjM=
decodes to:
api_key_123
So never use Base64 alone to protect sensitive information.
Base64 is useful for representation and transport, not security.
Final thoughts
Base64 decoding is easy when the input is clean ASCII text.
But real-world Base64 often includes images, files, Unicode, Base64URL, missing padding, or binary data.
The safest approach is to decode carefully and inspect the output type.
For fast testing, debugging, and file/image recovery, DecodingBase64 can help because it runs client-side and supports text, image, hex, and file outputs.
Remember:
Base64 decoding gives you bytes. What those bytes mean depends on the original data.