How to Decode Base64 in Python

Step-by-step guide to encoding and decoding Base64 in Python — strings, files, URL-safe, and error handling.

The base64 Module

Python has a built-in base64 module — no installation needed. It handles standard Base64, URL-safe Base64, and file encoding.

Encoding a String to Base64

import base64

text = "Hello, World!"

# Encode string to Base64
encoded = base64.b64encode(text.encode("utf-8")).decode("utf-8")
print(encoded)
# → SGVsbG8sIFdvcmxkIQ==

Note: b64encode() takes bytes, not a string. Use .encode("utf-8") to convert first. The result is also bytes — use .decode("utf-8") to get a string back.

Decoding a Base64 String

import base64

encoded = "SGVsbG8sIFdvcmxkIQ=="

# Decode Base64 back to string
decoded = base64.b64decode(encoded).decode("utf-8")
print(decoded)
# → Hello, World!

URL-Safe Base64 (for JWTs)

Standard Base64 uses + and / which break URLs. JWTs and many APIs use URL-safe Base64 (- and _ instead):

import base64

# URL-safe encode
encoded = base64.urlsafe_b64encode(b"Hello+World").decode("utf-8")
print(encoded)
# → SGVsbG8rV29ybGQ=

# URL-safe decode
decoded = base64.urlsafe_b64decode(encoded).decode("utf-8")
print(decoded)
# → Hello+World

# Decoding a JWT payload (middle section)
jwt_payload = "eyJ1c2VyIjoiYWxpY2UiLCJyb2xlIjoiYWRtaW4ifQ"
# Add padding if missing
padded = jwt_payload + "=" * (-len(jwt_payload) % 4)
payload = base64.urlsafe_b64decode(padded).decode("utf-8")
print(payload)
# → {"user":"alice","role":"admin"}

Encoding & Decoding Files

import base64

# Encode a file to Base64
with open("image.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

# Save encoded string to a text file
with open("image_base64.txt", "w") as f:
    f.write(encoded)

# Decode Base64 back to a file
with open("image_base64.txt", "r") as f:
    encoded = f.read()

with open("decoded_image.png", "wb") as f:
    f.write(base64.b64decode(encoded))

Handling Padding Errors

A common error is binascii.Error: Incorrect padding. This happens when the Base64 string is missing = padding (common with JWTs and some APIs):

import base64

def safe_b64decode(data: str) -> bytes:
    """Decode Base64 with automatic padding correction."""
    # Add missing padding
    missing = len(data) % 4
    if missing:
        data += "=" * (4 - missing)
    return base64.b64decode(data)

result = safe_b64decode("SGVsbG8")
print(result.decode("utf-8"))
# → Hello

Quick Reference

Frequently Asked Questions