How to convert Base64 to text, image and file
How to convert Base64 back to text, image and file in the browser and on the command line, with the UTF-8 gotcha, the Data URI prefix and common errors.
You open the JSON that came back from an API and somewhere in the payload there's a giant field starting with iVBORw0KGgo. Or you get an email with an attachment and the server spat out an endless block of text in the header. Or you find a data:image/png;base64,... in someone's CSS and just want to see what image that is without opening a browser. In every one of these cases the question is the same: how do I unpack this Base64 back into something that makes sense — text, image, or file?
This guide is the practical half. I'll walk through the three cases you hit day to day (string to text, Base64 to image, file to Base64 and back), how to do it in the browser, on the command line, and the mistakes that make the decoder blow up in your face. If you don't yet know what Base64 is or why it isn't encryption, read what Base64 is and why it shows up everywhere first — here I assume the concept is already clear.
Case 1: Base64 string back to text
The simplest case. You have b2xhIG11bmRv and want the original text. In the browser the pair is btoa (encode) and atob (decode):
btoa("ola mundo") // "b2xhIG11bmRv"
atob("b2xhIG11bmRv") // "ola mundo"
Works — until an accent or a symbol shows up. btoa treats each character as a byte in the Latin-1 range (0–255): btoa("€") throws InvalidCharacterError, because "€" is outside that range, and btoa("ação") doesn't even fail — it returns Yefjbw==, the Latin-1 Base64 of "ação", while the same text in UTF-8 is YcOnw6Nv. Whoever decodes it as UTF-8 on the other side gets garbage. This is the famous UTF-8 gotcha. The fix is to convert the string into UTF-8 bytes before encoding:
// encode safe for accents and emoji
const b64 = btoa(String.fromCharCode(...new TextEncoder().encode("ação €")));
// decode back
const txt = new TextDecoder().decode(
Uint8Array.from(atob(b64), c => c.charCodeAt(0))
);
TextEncoder turns the text into real UTF-8 bytes; btoa then encodes those bytes. On the way back, atob returns the bytes and TextDecoder reassembles them as UTF-8. Skip that step and you'll see "ção" instead of "ação" — the classic mojibake.
On the command line the problem disappears, because Unix tools have always worked with bytes:
echo -n "ação" | base64 # encodes accents correctly
echo "YcOnw6Nv" | base64 -d
The -n on echo matters: without it you encode an extra \n at the end and the result won't match the browser's. To check a one-off string without opening a terminal, the Base64 decoder shows the UTF-8 text right in the browser.
Case 2: Base64 to image (and the Data URI prefix)
This is where the most common confusion lives. A raw Base64 string — just the characters A–Z a–z 0–9 + / — is not an image. It's the representation of the file's bytes. For the browser to treat it as an image, you need the Data URI prefix that declares the type:
data:image/png;base64,iVBORw0KGgoAAAANS...
That data:image/png;base64, isn't decoration. It tells the browser the MIME type (image/png) and the encoding scheme (base64). Drop it into the src of an <img> and the image appears:
<img src="data:image/png;base64,iVBORw0KGgoAAAANS..." alt="">
Get the MIME type wrong — image/jpeg on a PNG — and depending on the browser the image won't even render. If you only have the raw Base64 blob without the prefix, you need to know the original format to rebuild the Data URI correctly. Tip: PNG always starts with iVBOR, JPEG with /9j/, GIF with R0lGOD. Those are the first bytes of each format's header, encoded.
To rebuild a real image file from raw Base64 on the command line:
# strip the data:... prefix first, if present
base64 -d image.b64 > image.png
In the browser, to download the decoded image:
const bytes = Uint8Array.from(atob(rawB64), c => c.charCodeAt(0));
const blob = new Blob([bytes], { type: "image/png" });
const url = URL.createObjectURL(blob);
// use url in the href of an <a download> or the src of an <img>
Notice I use the same Uint8Array.from(atob(...)) trick from the text case here — because an image is just binary bytes, not text. Treating binary bytes as a string and pushing them through a TextDecoder would corrupt the file. If you just want the round trip without writing code, you can paste the string and see the result directly in the Quick Tools Base64 to image converter, which takes raw Base64 or the data URL, previews the image with its format and dimensions, and saves the original file.
Case 3: any file to Base64 and back
PDF, ZIP, font, audio — any binary file becomes Base64 the same way, because to the encoder everything is a sequence of bytes. The typical use: embedding a file inside a JSON or a database field that only takes text.
Command line, round trip:
base64 document.pdf > document.b64 # encode
base64 -d document.b64 > document.pdf # decode
For large files, remember Base64 inflates the size by ~33% — three bytes become four characters. Sending a 50MB video as Base64 in a JSON payload is asking for a timeout. Use Base64 for small things (icons, certificates, thumbnails); for big files, upload the binary and send only the URL.
With openssl the result is the same, handy when you're already in the context of keys and certificates:
openssl base64 -in key.pem -out key.b64
openssl base64 -d -in key.b64 -out key.pem
One practical difference: openssl base64 wraps its output into 64-character lines by default, while many parsers expect a single line. If the decoder complains, strip the newlines first.
The mistakes that make the decoder blow up
Four traps account for almost every "why won't this decode":
- Wrong or missing padding. Base64 uses
=at the end to complete the last group. A length that isn't a multiple of 4, or=stripped by some overzealous sanitization, breaks strict decoders. If the string looks truncated at the end, that's almost always it. - URL-safe variant. When Base64 travels in a URL or a JWT,
+becomes-and/becomes_. A standard decoder doesn't recognize-and_and fails. Convert back (-→+,_→/) before decoding, or use the dedicated URL-safe function. - Spaces and line breaks pasted along. Copying from an email or a terminal drags
\nand spaces with it. Most decoders tolerate it, some don't. When in doubt, strip whitespace first. - Thinking it's encryption. Base64 is encoding, not security. Anyone decodes it in a second. Never, ever "hide" a password or token by just Base64-ing it — that's the digital equivalent of hiding the key under the doormat.
Frequently asked questions
How do I know if a Base64 string is text, image, or file?
By the first characters of the decoded content, which correspond to the format's header. iVBOR is PNG, /9j/ is JPEG, JVBERi is PDF, UEsDB is ZIP/Office. If you decode it and get readable text, it was text. A decent converter detects this automatically and shows the right preview.
Why do my accents turn into garbage after decoding?
Because the encoding didn't go through UTF-8. The browser's btoa/atob work byte by byte in the Latin-1 range; if you don't convert with TextEncoder/TextDecoder, characters outside Latin-1 (€, emoji) throw and accented characters come out as Latin-1, not UTF-8. Use the TextEncoder pair on encode and TextDecoder on decode. On the command line, base64 handles UTF-8 bytes natively.
Do I really need the data:image/png;base64, prefix?
For the browser to render it via an <img> src or in CSS, yes — it's what declares the content type. To rebuild the file on disk with base64 -d, no: there you decode only the bytes, and the prefix, if present, must be removed first or the file comes out corrupted.
Does Base64 increase the file size?
Yes, by around 33%. Every three binary bytes become four ASCII characters. That's why Base64 only makes sense for small things embedded in text; for large files the size and parsing overhead isn't worth it.
What to take from this guide
Decoding Base64 is always the same move: separate the prefix (if any), recognize the variant (standard or URL-safe), and treat the content as bytes — not as text — when it's an image or a file. The btoa/atob UTF-8 gotcha and missing padding account for 90% of the headaches; fix those two and the rest is mechanical. And remember Base64 never was and never will be security: it's byte transport in text form, full stop.
- 01 Does the PageSpeed Score Affect SEO? 100/100 and Failing Google doesn't rank on PageSpeed's 0 to 100 score but on Core Web Vitals from real users. Here's why a site scores 100/100 and still fails in the field.
- 02 Unit test vs integration test: the difference in practice The difference between unit and integration tests with API and database examples: what each one catches, what it costs, and when to use each in your project.