Base64 Encoding in Python: Complete Guide

← Back to Blog

Base64 Encoding in Python: Complete Guide

· 5 min read

Python base64 Module Overview

Python's standard library base64 module provides complete Base64 encoding and decoding functionality without installing any third-party packages. The module supports multiple Base64 variants, including standard Base64, URL-safe Base64 (Base64URL), and variants for MIME email.

Unlike JavaScript, Python's base64 module operates on bytes types, not strings. This is because Python 3 strictly distinguishes between text (str, Unicode strings) and binary data (bytes). Understanding this is crucial for using the base64 module correctly.

Basic Encoding and Decoding

import base64

# 编码字符串 / Encode a string
text = "Hello, World!"
# 先将字符串转为 bytes / First convert string to bytes
encoded = base64.b64encode(text.encode('utf-8'))
print(encoded)          # b'SGVsbG8sIFdvcmxkIQ=='
print(encoded.decode()) # 'SGVsbG8sIFdvcmxkIQ=='

# 解码 / Decode
decoded_bytes = base64.b64decode('SGVsbG8sIFdvcmxkIQ==')
decoded_text = decoded_bytes.decode('utf-8')
print(decoded_text)     # 'Hello, World!'

# 编码中文 / Encode Chinese text
chinese = "你好，世界！"
encoded_cn = base64.b64encode(chinese.encode('utf-8'))
print(encoded_cn.decode()) # '5L2g5aW977yM5LiW55WM77yB'

Note that b64encode() accepts bytes type and returns bytes type. If you need a string, call .decode('ascii') or .decode() (default UTF-8, but Base64 output only contains ASCII characters).

Encoding and Decoding Files

import base64

# 将图片文件编码为 Base64 / Encode image file to Base64
with open('image.png', 'rb') as f:
    image_data = f.read()
    encoded = base64.b64encode(image_data).decode('ascii')
    print(f"data:image/png;base64,{encoded}")

# 将 Base64 字符串解码并保存为文件
# Decode Base64 string and save as file
def decode_to_file(base64_str, output_path):
    data = base64.b64decode(base64_str)
    with open(output_path, 'wb') as f:
        f.write(data)
    print(f"Saved {len(data)} bytes to {output_path}")

decode_to_file(encoded, 'output.png')

Key point: when reading binary files you must use 'rb' mode (binary read), and 'wb' mode (binary write) when writing. If you use text mode 'r', Python will attempt to interpret file contents as text, corrupting binary data.

URL-Safe Base64 Encoding and Decoding

import base64

data = b'\xfb\xff\xfe'

# 标准 Base64（包含 + 和 /）
# Standard Base64 (contains + and /)
std = base64.b64encode(data)
print(std)     # b'+//+'  (举例，实际值根据数据而定)

# URL 安全 Base64（+ 替换为 -，/ 替换为 _）
# URL-safe Base64 (+ replaced with -, / replaced with _)
url_safe = base64.urlsafe_b64encode(data)
print(url_safe) # b'-__-'

# URL 安全 Base64 解码
# URL-safe Base64 decoding
decoded = base64.urlsafe_b64decode(url_safe)
print(decoded == data)  # True

# 处理无填充的 Base64URL（如 JWT）
# Handle unpadded Base64URL (like JWT)
def decode_jwt_part(base64url_str):
    # 补全填充
    padding = 4 - len(base64url_str) % 4
    if padding != 4:
        base64url_str += '=' * padding
    return base64.urlsafe_b64decode(base64url_str)

Handling Base64 Decode Errors

Python's base64.b64decode() is fairly strict about input and raises binascii.Error when encountering illegal characters. You can pass validate=False (the default) to have the function ignore illegal characters, or use validate=True to enforce validation.

import base64
import binascii

def safe_b64decode(s):
    try:
        # 添加填充并解码 / Add padding and decode
        if isinstance(s, str):
            s = s.encode('ascii')
        # 补全填充
        s += b'=' * (4 - len(s) % 4)
        return base64.b64decode(s)
    except (binascii.Error, ValueError) as e:
        print(f"Decode error: {e}")
        return None

result = safe_b64decode('SGVsbG8')
print(result)  # b'Hello'

Using Base64 in Web Frameworks

In web frameworks like Flask or Django, Base64 is commonly used for handling HTTP Basic Auth or receiving image data uploaded from the frontend. Here's an example of parsing Basic Auth headers in Flask:

from flask import request
import base64

def get_basic_auth():
    auth_header = request.headers.get('Authorization', '')
    if not auth_header.startswith('Basic '):
        return None, None

    try:
        credentials = base64.b64decode(
            auth_header[6:]
        ).decode('utf-8')
        username, password = credentials.split(':', 1)
        return username, password
    except Exception:
        return None, None

Note that the 1 parameter in split(':', 1) is very important: it ensures splitting only at the first colon, allowing passwords to contain colons (which are valid password characters).

Base64 with Byte Streams

Python's base64 module also provides streaming interfaces, suitable for handling large files. base64.encodebytes() and base64.decodebytes() automatically insert a newline every 76 characters (conforming to MIME standards), suitable for generating email attachment-format Base64 data.

import base64

# MIME 格式（每76字符换行）/ MIME format (newline every 76 chars)
with open('document.pdf', 'rb') as f:
    data = f.read()
    mime_base64 = base64.encodebytes(data)
    print(mime_base64[:100])  # 查看前100字节

The difference between encodebytes() and b64encode() is that the former includes newlines while the latter produces a continuous string without newlines. Use b64encode() when generating API request bodies, and encodebytes() when generating PEM certificates or MIME attachments.

Try the online tool now — no installation, completely free.

Open Tool →