Base64 to Text Python: Decoding With the base64 Module

The bytes boundary

b64decode returns bytes, always. Turning those into a string is a separate decision, and Python makes you state it:

import base64

raw  = base64.b64decode('aGVsbG8=')   # b'hello'
text = raw.decode('utf-8')            # 'hello'

# encoding, the other direction
base64.b64encode('hello'.encode('utf-8')).decode('ascii')

The final .decode("ascii") on encode is safe because Base64 output is always ASCII. The .decode("utf-8") on the way back is the one that can fail, and it should — it means the bytes were not UTF-8 text.

Padding errors

binascii.Error: Incorrect padding means the length is not a multiple of 4. Strings copied from JSON, logs or URLs frequently lose their =:

def decode_padded(s: str) -> bytes:
    return base64.b64decode(s + '=' * (-len(s) % 4))

validate=False is the default and silently ignores characters outside the alphabet. Pass validate=True when you want malformed input to raise rather than decode into something unexpected.

URL-safe variants and binary

JWTs and URL parameters use - and _ in place of + and /. Use the dedicated functions rather than string replacement:

base64.urlsafe_b64decode(token_part + '==')
base64.urlsafe_b64encode(data).rstrip(b'=')

And if the payload is not text, do not call .decode() at all — write the bytes to a file in binary mode. Checking the first bytes tells you which case you are in: b"%PDF", b"\x89PNG", b"PK".

Frequently asked questions

Why does b64decode reject my string?

Missing padding, or characters outside the alphabet. Pad to a multiple of 4, or use urlsafe_b64decode for token strings.

Why does .decode() raise UnicodeDecodeError?

The decoded bytes are not UTF-8 text — most likely binary data such as an image or archive.

Can b64encode take a str?

No. Call .encode() first, choosing the character encoding explicitly.