Developer Guide
Base64 Encoding in Python
base64.b64encode takes bytes, not str. Encode UTF-8 text, use urlsafe_b64encode for - and _, read files in rb, then check the ASCII against the browser tool.
Python will not let you pretend a str is a byte string. base64.b64encode(b'hello') returns b'aGVsbG8='. base64.b64encode('hello') raises TypeError: a bytes-like object is required, not 'str'. That error is the whole lesson: encode text to bytes (almost always UTF-8), run the alphabet, then .decode('ascii') if you need a Python str for JSON.
The stdlib module is base64. It has standard and URL-safe helpers, and it works the same on a buffer you read from disk in 'rb' mode. None of that runs on a server at thedevtools.in — /tools/base64 is a browser check against the same alphabet, Unicode-safe, with a URL-safe toggle. This page is Python-only; the JavaScript btoa / Buffer path lives in a sibling guide.
b64encode requires bytes
b64encode maps every three input bytes to four ASCII bytes in A–Z a–z 0–9 + /, with = padding. The return type is bytes. b64decode accepts bytes or ASCII str and returns bytes.
If you need a JSON string, decode the Base64 bytes as ASCII — the alphabet is ASCII by definition. Do not .decode('utf-8') the Base64 output; that happens to work but suggests you think the payload is text. The payload is an alphabet. The original message, if it was text, is recovered with b64decode(...).decode('utf-8').
import base64
base64.b64encode(b'hello')
# b'aGVsbG8='
base64.b64encode(b'hello').decode('ascii')
# 'aGVsbG8='
base64.b64decode(b'aGVsbG8=')
# b'hello'
base64.b64decode('SGVsbG8gV29ybGQh').decode('utf-8')
# 'Hello World!'Unicode: encode UTF-8 yourself
A Python str is Unicode. Base64 does not see characters; it sees bytes. Call .encode('utf-8') before b64encode, and .decode('utf-8') after b64decode. That pair is what /tools/base64 does in the browser, so the strings match across languages.
Latin-1 .encode('latin-1') will throw on emoji and on Devanagari. Do not pick it to “match JavaScript btoa” unless you are reproducing a Latin-1 bug on purpose. If a partner sends Base64 of UTF-16LE bytes, you must decode that encoding after b64decode — the alphabet does not record which text encoding was used.
base64.b64encode('नमस्ते'.encode('utf-8'))
# b'4KSo4KSu4KS44KWN4KSk4KWH'
base64.b64decode(
b'4KSo4KSu4KS44KWN4KSk4KWH'
).decode('utf-8')
# 'नमस्ते'urlsafe_b64encode
urlsafe_b64encode replaces + with - and / with _. Padding = is still present when the length needs it. /tools/base64 URL-safe mode maps +/ → -_ and omits padding, which matches JWT-style Base64url more closely than CPython’s default.
<<??>> does not need padding in either dialect: standard PDw/Pz4+, URL-safe PDw_Pz4-. One byte does: urlsafe_b64encode(b'h') is b'aA=='; the browser tool’s URL-safe mode shows aA. Strip = with .rstrip(b'=') only when the receiver told you to. urlsafe_b64decode still accepts padded input.
base64.b64encode(b'<<??>>')
# b'PDw/Pz4+'
base64.urlsafe_b64encode(b'<<??>>')
# b'PDw_Pz4-'
base64.urlsafe_b64encode(b'h')
# b'aA=='Files: open in rb
Text mode ('r') on Windows can change newlines and will refuse undecodable bytes. Base64 a file as a binary blob: 'rb', read, encode. For an image you plan to paste into HTML, /tools/image-to-base64 already builds a data URI in the browser; Python is for scripts and servers you run yourself.
Write the reverse with 'wb' after b64decode. If you received a data URI, split on the comma and decode only the payload. /tools/base64-to-image needs that data:image/TYPE;base64, prefix; the stdlib does not.
with open('photo.png', 'rb') as f:
encoded = base64.b64encode(f.read())
with open('photo.png', 'wb') as f:
f.write(base64.b64decode(encoded))Validate against the browser tool
Print the ASCII str (not the b'...' repr) and paste it into /tools/base64. hello must decode to hello. 4KSo4KSu4KS44KWN4KSk4KWH must decode to नमस्ते. If Python and the tab disagree, you encoded the wrong bytes — UTF-16, a trailing newline from input(), or a file opened in text mode.
The on-site tool does not run Python and does not upload the string. It is a second implementation of the same alphabet, useful because copy-paste errors show up immediately.
Common pitfalls
Passing a str to b64encode. Decoding UTF-8 text as Latin-1 after b64decode. Mixing urlsafe_b64encode output with a standard decoder (- and _ are not + and /). Leaving Python’s == padding on a JWT that forbids it — or stripping padding for a decoder that requires it.
b64decode is not encryption. validate=True (3.11+) rejects non-alphabet characters; without it, some garbage is ignored. MIME b64encode wraps at 76 characters; strip whitespace before a strict decode.
b64encodewantsbytes; encode thestrfirst.- URL-safe in CPython still pads; the browser tool may not.
- Open files
'rb'/'wb'.
Worked examples
ASCII hello
base64.b64encode(b'hello')b'aGVsbG8='Decode mode on /tools/base64 with aGVsbG8= returns hello.
UTF-8 Devanagari
base64.b64encode('नमस्ते'.encode('utf-8')).decode('ascii')4KSo4KSu4KS44KWN4KSk4KWHPaste that ASCII into /tools/base64 — the tool is Unicode-safe and should show नमस्ते.
URL-safe six bytes
base64.urlsafe_b64encode(b'<<??>>')b'PDw_Pz4-'Standard b64encode of the same bytes is b'PDw/Pz4+'.
Frequently asked questions
Why is b64encode a TypeError on a str?
It only accepts bytes-like objects. Call 'hello'.encode('utf-8') (or pass b'hello') first.
How do I get a str for JSON?
base64.b64encode(data).decode('ascii'). The alphabet is ASCII. Put that string in the JSON field.
Does urlsafe_b64encode omit padding?
No. CPython keeps =. /tools/base64 URL-safe mode omits padding. Strip with .rstrip(b'=') only when the other side expects Base64url.
Can I encode a file as text?
Not if you care about bytes. Use 'rb'. For a quick data URI of a local image, /tools/image-to-base64 reads the file in the browser.
Does thedevtools.in run this Python?
No. The stdlib runs on your machine. /tools/base64 is a client-side check of the same alphabet.
Summary
Feed b64encode bytes, UTF-8-encode Unicode yourself, pick urlsafe_b64encode only when the receiver wants - and _, and read files in 'rb'. Then paste the ASCII into /tools/base64 — hello must come back as hello, and PDw_Pz4- is the URL-safe form of <<??>>.