Base64 Encode Python — b64encode() Guide

Maria Santos·Backend Developer·Reviewed byPriya Sharma·Published 2026-03-13

Use the free online Base64 Encode Online directly in your browser — no install required.

When you build Python services that pass credentials in HTTP Basic Auth headers, embed binary assets in API responses, or store TLS certificates in environment variables, you end up writing base64 encode Python code on a regular basis. Python ships the base64 module in the standard library — no pip install needed — but the bytes-vs-string distinction and the difference between b64encode, urlsafe_b64encode, and encodebytes trip up developers more often than you might expect. For a quick encode without writing any code, ToolDeck's Base64 Encoder handles it instantly in the browser. This guide covers the full stdlib API, URL-safe encoding for JWTs, file and API response scenarios, CLI shortcuts, a high-performance alternative, and the four mistakes I see most often during code review.

✓base64.b64encode() expects bytes, not str — always call .encode("utf-8") on the input string before passing it in
✓The return value is also bytes — call .decode("utf-8") or .decode("ascii") to get a plain str you can embed in JSON or HTTP headers
✓base64.urlsafe_b64encode() replaces + → - and / → _ but keeps = padding — strip it manually with .rstrip("=") for JWT segments
✓base64.encodebytes() inserts a \n every 76 characters (MIME format) — never use it for data URIs, JSON fields, or environment variables
✓pybase64 (C extension, drop-in API) encodes 2–10× faster than stdlib; worth it for high-throughput services processing large payloads

What is Base64 Encoding?

Base64 converts arbitrary binary data into a string built from 64 printable ASCII characters: A–Z, a–z, 0–9, +, and /. Every 3 input bytes map to exactly 4 Base64 characters. If the input length is not a multiple of 3, one or two = padding characters are appended. The encoded output is always about 33% larger than the original.

Base64 is not encryption — it provides no confidentiality whatsoever. Its purpose is transport safety: many protocols and storage systems were designed for 7-bit ASCII text and cannot safely carry arbitrary binary bytes. Base64 bridges that gap. Common Python use cases include HTTP Basic Auth headers, data URIs for inlining images in HTML or CSS, JWT token segments, email MIME attachments, and passing binary blobs through environment variables or JSON APIs.

Before · text

After · text

deploy-svc:sk-prod-9f2a1c3e8b4d

ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==

base64.b64encode() — Standard Encoding Guide with Examples

base64.b64encode(s, altchars=None)is the primary encoding function in Python's stdlib. It lives in the base64 module, which ships with every Python installation. The function accepts a bytes object and returns a bytes object containing the ASCII Base64 representation. Python 3.x (3.6+) is assumed throughout this guide.

Minimal working example

Python 3.6+

import base64

# Encoding an API credential pair for an HTTP Basic Auth header
service_id = "deploy-svc"
api_key    = "sk-prod-9f2a1c3e8b4d"

credential_bytes   = f"{service_id}:{api_key}".encode("utf-8")
encoded_bytes      = base64.b64encode(credential_bytes)
encoded_str        = encoded_bytes.decode("ascii")  # bytes → str

print(encoded_str)
# ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==

import urllib.request

req = urllib.request.Request("https://api.internal/v1/deployments")
req.add_header("Authorization", f"Basic {encoded_str}")
# Header value: Basic ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==

Extended example — sort_keys, nested objects, round-trip decode

Python 3.6+

import base64
import json

# Encoding a structured server configuration for an env variable
server_config = {
    "host":           "db-primary.eu-west-1.internal",
    "port":           5432,
    "database":       "analytics_prod",
    "max_connections": 150,
    "ssl": {
        "mode":          "verify-full",
        "cert_path":     "/etc/ssl/certs/db-client.crt",
        "reject_self_signed": True,
    },
}

config_json    = json.dumps(server_config, sort_keys=True)
encoded_bytes  = base64.b64encode(config_json.encode("utf-8"))
encoded_str    = encoded_bytes.decode("ascii")

print(encoded_str[:60] + "...")
# eyJkYXRhYmFzZSI6ICJhbmFseXRpY3NfcHJvZCIsICJob3N0IjogImRi...

# Decode and round-trip
decoded_json   = base64.b64decode(encoded_str).decode("utf-8")
restored       = json.loads(decoded_json)

print(restored["host"])            # db-primary.eu-west-1.internal
print(restored["ssl"]["mode"])     # verify-full

Note:b64decode() is lenient by default — it silently ignores invalid characters including whitespace and newlines. Pass validate=True to raise a binascii.Error on any non-Base64 character. Use this when decoding untrusted input from external systems.

Encoding Non-ASCII and Unicode Strings in Python

Python 3 strings are Unicode by default. The base64 module operates on bytes, not on str — so you must encode the string to bytes before passing it in. The choice of encoding matters: UTF-8 handles every Unicode code point and is the right default for almost all use cases.

Python 3.6+

import base64

# Encoding multilingual content — user display names from an international platform
user_names = [
    "Мария Соколова",      # Cyrillic — U+041C and above
    "田中太郎",              # CJK ideographs — 3 bytes each in UTF-8
    "Sarah Chen",           # ASCII — 1 byte per character
    "José Rodríguez",       # Latin extended — é is 2 bytes in UTF-8
]

for name in user_names:
    encoded = base64.b64encode(name.encode("utf-8")).decode("ascii")
    decoded = base64.b64decode(encoded).decode("utf-8")

    print(f"Original : {name}")
    print(f"Encoded  : {encoded}")
    print(f"Roundtrip: {decoded}")
    print(f"Match    : {name == decoded}")
    print()

# Original : Мария Соколова
# Encoded  : 0JzQsNGA0LjRjyDQodC+0LrQvtC70L7QstCw
# Roundtrip: Мария Соколова
# Match    : True

Note:If you need to confirm the encoding is correct for a particular string, paste the Base64 output directly into ToolDeck's Base64 Encoder — it decodes in real time and shows the exact UTF-8 byte representation. Useful when debugging Cyrillic, CJK, or emoji in payload strings.

base64 Module — Functions Reference

The base64 module exposes several encoding functions. Here is the complete reference for the ones you will encounter in practice:

Function	Input	Returns	Description
b64encode(s, altchars=None)	bytes	bytes	Standard Base64 (RFC 4648 §4). altchars replaces the + and / characters with two custom bytes.
b64decode(s, altchars=None, validate=False)	bytes \| str	bytes	Decodes standard Base64. validate=True raises binascii.Error on invalid input characters.
urlsafe_b64encode(s)	bytes	bytes	URL-safe Base64 (RFC 4648 §5). Uses - and _ instead of + and /. Keeps = padding.
urlsafe_b64decode(s)	bytes \| str	bytes	Decodes URL-safe Base64. Accepts both padded and unpadded input.
encodebytes(s)	bytes	bytes	MIME Base64: inserts \n every 76 characters and appends a trailing \n. For email/MIME only.
decodebytes(s)	bytes	bytes	Decodes MIME Base64. Ignores whitespace and embedded newlines.
b16encode(s)	bytes	bytes	Hex encoding (Base16). Each byte becomes two uppercase hex characters. No padding.
b32encode(s)	bytes	bytes	Base32 encoding. Uses A–Z and 2–7. Larger output than Base64; used in TOTP secrets.

The altchars parameter in b64encode accepts a 2-byte object that substitutes the + and / characters. Passing altchars=b'-_' produces output identical to urlsafe_b64encode but lets you control padding separately.

URL-Safe Base64 — urlsafe_b64encode() for JWTs and Query Parameters

Standard Base64 uses + and /, both of which are reserved characters in URLs. A + in a query string is decoded as a space, and / is a path separator. When the encoded value appears in a URL, a filename, or a cookie, you need the URL-safe variant: urlsafe_b64encode() substitutes - for + and _ for /.

JWTs use URL-safe Base64 withoutpadding for all three segments (header, payload, signature). The padding must be stripped manually — Python's stdlib keeps it.

Encoding a JWT payload segment

Python 3.6+

import base64
import json

def encode_jwt_segment(data: dict) -> str:
    """Encode a dict as a URL-safe Base64 string without padding (JWT format)."""
    json_bytes = json.dumps(data, separators=(",", ":")).encode("utf-8")
    return base64.urlsafe_b64encode(json_bytes).rstrip(b"=").decode("ascii")

def decode_jwt_segment(segment: str) -> dict:
    """Decode a URL-safe Base64 JWT segment (handles missing padding)."""
    # Add back padding: Base64 requires length to be a multiple of 4
    padding  = 4 - len(segment) % 4
    padded   = segment + ("=" * (padding % 4))
    raw      = base64.urlsafe_b64decode(padded)
    return json.loads(raw)

# Build a JWT header and payload
header  = {"alg": "HS256", "typ": "JWT"}
payload = {
    "sub":       "usr_7c3a9f1b2d",
    "workspace": "ws_eu-west-1-prod",
    "role":      "data-engineer",
    "iat":       1741824000,
    "exp":       1741910400,
}

header_segment  = encode_jwt_segment(header)
payload_segment = encode_jwt_segment(payload)

print(header_segment)
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

print(payload_segment)
# eyJzdWIiOiJ1c3JfN2MzYTlmMWIyZCIsIndvcmtzcGFjZSI6IndzX2...

# Verify round-trip
restored = decode_jwt_segment(payload_segment)
print(restored["role"])  # data-engineer

Note:urlsafe_b64decode() accepts both padded and unpadded input as of Python 3.x, but only if the characters are URL-safe (- and _). Never pass a standard Base64 string (with + or /) to urlsafe_b64decode — the mismatched characters will cause silent data corruption or a binascii.Error.

Encoding Files and API Responses in Python

In production code, Base64 encoding most commonly appears around files being transmitted and around responses from external APIs that deliver binary content. Both scenarios require careful handling of the bytes boundary.

Reading a file from disk and encoding it

Python 3.6+

import base64
import json
from pathlib import Path

def encode_file_to_base64(file_path: str) -> str:
    """Read a binary file and return its Base64-encoded representation."""
    try:
        raw_bytes = Path(file_path).read_bytes()
        return base64.b64encode(raw_bytes).decode("ascii")
    except FileNotFoundError:
        raise FileNotFoundError(f"File not found: {file_path}")
    except PermissionError:
        raise PermissionError(f"Permission denied reading: {file_path}")

# Attach a TLS certificate to a deployment manifest
cert_b64 = encode_file_to_base64("./ssl/service-client.crt")

deployment_manifest = {
    "service":     "payment-processor",
    "environment": "production",
    "region":      "eu-west-1",
    "tls": {
        "client_cert":     cert_b64,
        "cert_format":     "base64-pem",
    },
}

# Write the manifest — cert is safely embedded as a string
with open("./dist/deployment-manifest.json", "w") as f:
    json.dump(deployment_manifest, f, indent=2)

print(f"Certificate encoded: {len(cert_b64)} characters")

Encoding an HTTP API response for debugging

Python 3.6+

import base64
import requests  # pip install requests

def fetch_and_encode_binary(url: str, headers: dict | None = None) -> str:
    """Fetch a binary resource from an API and return it as Base64."""
    response = requests.get(url, headers=headers or {}, timeout=10)
    response.raise_for_status()  # raises HTTPError for 4xx/5xx

    content_type = response.headers.get("Content-Type", "unknown")
    encoded      = base64.b64encode(response.content).decode("ascii")

    print(f"Content-Type : {content_type}")
    print(f"Raw size     : {len(response.content):,} bytes")
    print(f"Encoded size : {len(encoded):,} characters")
    return encoded

# Example: download a signed PDF invoice from an internal billing API
invoice_b64 = fetch_and_encode_binary(
    "https://billing.internal/api/v2/invoices/INV-2026-0042/pdf",
    headers={"Authorization": "Bearer eyJhbGc..."},
)

# Attach to a notification payload
notification = {
    "recipient_id":  "team-finance",
    "invoice_id":    "INV-2026-0042",
    "attachment": {
        "filename":     "invoice-2026-0042.pdf",
        "content":      invoice_b64,
        "content_type": "application/pdf",
        "encoding":     "base64",
    },
}
print(f"Payload ready: {len(str(notification)):,} characters")

How to Base64 Encode an Image File in Python

Encoding an image to Base64 and embedding it as a data URI is the standard approach for HTML email templates, PDF generation, and self-contained HTML snapshots. The browser interprets the encoded string directly — no separate image request is needed. The same pattern works for any binary file type: PNG, JPEG, SVG, WebP, or PDF.

Python 3.6+

import base64
import mimetypes
from pathlib import Path

def image_to_data_uri(image_path: str) -> str:
    """Convert an image file to a Base64 data URI for inline HTML embedding."""
    path      = Path(image_path)
    mime_type = mimetypes.guess_type(image_path)[0] or "image/octet-stream"
    raw_bytes = path.read_bytes()
    encoded   = base64.b64encode(raw_bytes).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"

# Embed product images inline in an HTML email template
hero_uri      = image_to_data_uri("./assets/product-hero-768px.png")
thumbnail_uri = image_to_data_uri("./assets/product-thumb-128px.webp")

html_fragment = f"""
<img src="{hero_uri}"
     alt="Product hero"
     width="768" height="432"
     style="display:block;max-width:100%" />
"""

print(f"PNG data URI starts with: {hero_uri[:60]}...")
# data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAwAAAAA...

Note:For SVG files, a data URI with URL-encoding (data:image/svg+xml,{encoded}) is often smaller than Base64 because SVG is text-based and Base64 inflates size by ~33%. Use Base64 for raster formats (PNG, JPEG, WebP) and URL-encoding for SVG.

Working with Large Files — Chunked Base64 Encoding

Loading an entire file into memory with Path.read_bytes() is fine for files up to ~50 MB. Above that threshold, peak memory usage becomes significant — a 200 MB file requires ~200 MB for the raw bytes plus ~267 MB for the Base64 output, totalling ~467 MB in a single process. For large files, read and encode in chunks instead.

The critical constraint: chunk size must be a multiple of 3 bytes. Base64 encodes 3 input bytes into exactly 4 output characters. If a chunk boundary falls on a non-multiple of 3, the encoder appends = padding mid-stream, making the concatenated output invalid.

Streaming encode to a file (no full-file memory load)

Python 3.6+

import base64
from pathlib import Path

CHUNK_SIZE = 3 * 1024 * 256  # 786,432 bytes — multiple of 3, ~768 KB per chunk

def encode_large_file(input_path: str, output_path: str) -> int:
    """
    Encode a large binary file to Base64 without loading it fully into memory.
    Returns the number of Base64 characters written.
    """
    total_chars = 0
    with open(input_path, "rb") as src, open(output_path, "w") as dst:
        while True:
            chunk = src.read(CHUNK_SIZE)
            if not chunk:
                break
            encoded_chunk = base64.b64encode(chunk).decode("ascii")
            dst.write(encoded_chunk)
            total_chars += len(encoded_chunk)
    return total_chars

# Encode a 300 MB product video for an asset delivery manifest
chars_written = encode_large_file(
    "./uploads/product-demo-4k.mp4",
    "./dist/product-demo-4k.b64",
)
print(f"Encoded: {chars_written:,} Base64 characters")
# Encoded: 407,374,184 Base64 characters

Encoding a directory of binary assets (NDJSON output)

Python 3.6+

import base64
import json
from pathlib import Path

def encode_assets_to_ndjson(asset_dir: str, output_path: str) -> int:
    """
    Encode all binary files in a directory to a NDJSON manifest.
    Each line is a JSON object: {"path": "...", "mime": "...", "data": "<base64>"}
    Returns the number of files processed.
    """
    import mimetypes

    asset_path = Path(asset_dir)
    count = 0

    with open(output_path, "w") as out:
        for file_path in sorted(asset_path.rglob("*")):
            if not file_path.is_file():
                continue
            mime = mimetypes.guess_type(str(file_path))[0] or "application/octet-stream"
            encoded = base64.b64encode(file_path.read_bytes()).decode("ascii")
            record  = {"path": str(file_path.relative_to(asset_path)), "mime": mime, "data": encoded}
            out.write(json.dumps(record) + "\n")
            count += 1

    return count

processed = encode_assets_to_ndjson("./dist/static/", "./dist/asset-bundle.ndjson")
print(f"Encoded {processed} files into NDJSON asset bundle")

Note:Switch from read_bytes() to chunked reading when the input file exceeds ~50–100 MB, or when your service processes many files concurrently and memory pressure becomes a concern. For files under 50 MB, the simpler b64encode(path.read_bytes()).decode() one-liner is faster and easier to reason about.

Command-Line Base64 Encoding with Python

Python ships a CLI interface for the base64 module — no additional tools needed. It works cross-platform, making it useful in CI pipelines and Windows environments where the system base64 command may not be available.

bash

# ── python -m base64 ───────────────────────────────────────────────────
# Encode a string (pipe stdin)
echo -n "deploy-svc:sk-prod-9f2a1c3e8b4d" | python3 -m base64
# ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==

# Encode a file
python3 -m base64 ./ssl/service-client.crt

# Decode a Base64 string
echo "ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==" | python3 -m base64 -d

# Decode a Base64 file back to binary
python3 -m base64 -d ./dist/service-client.b64 > ./restored.crt

# ── Python one-liner — cross-platform, works on Windows ────────────────
# Encode a string
python3 -c "import base64,sys; print(base64.b64encode(sys.argv[1].encode()).decode())" "my-secret"
# bXktc2VjcmV0

# URL-safe encode (no padding)
python3 -c "import base64,sys; print(base64.urlsafe_b64encode(sys.argv[1].encode()).rstrip(b'=').decode())" "my-secret"
# bXktc2VjcmV0

# Encode a file inline (result on stdout)
python3 -c "import base64,sys; print(base64.b64encode(open(sys.argv[1],'rb').read()).decode())" ./config.json

Note:Unlike the macOS system base64 command, python -m base64 does not wrap output at 76 characters by default. The output is a single unbroken line, which is what you want for environment variables, JSON fields, and HTTP headers. Use it as a drop-in for system base64 on any OS.

High-Performance Alternative: pybase64

Python's stdlib base64 module is implemented in pure Python (with a thin C layer in CPython). For services that encode large payloads at high throughput — image processing pipelines, bulk export jobs, real-time telemetry ingestion — pybase64 is a drop-in replacement backed by libbase64, a SIMD-accelerated C library. Benchmarks show 2–10× throughput improvements depending on payload size and CPU architecture.

bash

pip install pybase64

Python 3.6+

import pybase64
import time

# pybase64 is a drop-in replacement — same function signatures as stdlib
sample_payload = b"x" * (1024 * 1024)  # 1 MB of binary data

# Standard encoding — identical output to base64.b64encode()
encoded = pybase64.b64encode(sample_payload)
decoded = pybase64.b64decode(encoded)
assert decoded == sample_payload

# URL-safe encoding — identical output to base64.urlsafe_b64encode()
url_safe = pybase64.urlsafe_b64encode(sample_payload)

# b64encode_as_string() returns str directly — no .decode() call needed
telemetry_event = b'{"event":"page_view","session_id":"sess_3a7f91c2","ts":1741824000}'
encoded_str: str = pybase64.b64encode_as_string(telemetry_event)

print(encoded_str[:48] + "...")
# eyJldmVudCI6InBhZ2VfdmlldyIsInNlc3Npb25faWQi...

# Throughput comparison (approximate, varies by hardware)
# stdlib  base64.b64encode(1 MB):   ~80 MB/s
# pybase64.b64encode(1 MB):         ~800 MB/s (SIMD path on AVX2 CPU)

Switch to pybase64 when profiling shows Base64 encoding as a bottleneck, or when you encode payloads above ~100 KB repeatedly. For one-off encoding of small strings (credentials, tokens), the stdlib is fast enough and has no install dependency.

Terminal Output with Syntax Highlighting

When debugging Base64-encoded payloads in the terminal — particularly JSON configs or JWT contents — the rich library gives you syntax-highlighted, indented output that is far easier to read than a raw dump. It is especially useful in CLI tools, debugging scripts, and REPL sessions.

bash

pip install rich

Python 3.6+

import base64
import json
from rich import print as rprint
from rich.syntax import Syntax
from rich.console import Console

console = Console()

def decode_and_pretty_print(encoded: str, label: str = "Decoded payload") -> None:
    """Decode a Base64 string, parse as JSON, and print with syntax highlighting."""
    raw_bytes = base64.b64decode(encoded + "==")  # tolerant padding
    try:
        parsed  = json.loads(raw_bytes)
        pretty  = json.dumps(parsed, indent=2, ensure_ascii=False)
        syntax  = Syntax(pretty, "json", theme="monokai", line_numbers=False)
        console.rule(f"[bold blue]{label}")
        console.print(syntax)
    except json.JSONDecodeError:
        # Not JSON — print raw text
        console.rule(f"[bold yellow]{label} (raw text)")
        rprint(raw_bytes.decode("utf-8", errors="replace"))

# Inspect a JWT payload segment from a failed authentication request
jwt_payload_segment = "eyJzdWIiOiJ1c3JfN2MzYTlmMWIyZCIsInJvbGUiOiJkYXRhLWVuZ2luZWVyIiwiZXhwIjoxNzQxOTEwNDAwfQ"
decode_and_pretty_print(jwt_payload_segment, "JWT Payload")

Note:Use rich output only for terminal display — for debugging, logging to stdout, or interactive CLI tools. Never use it to write Base64 output to files, return it from API endpoints, or store it in environment variables, as rich adds ANSI escape codes that corrupt the data.

Common Mistakes

I've reviewed a lot of Python codebases with Base64 encoding, and these four mistakes appear consistently — often undiscovered until non-ASCII input or a binary file hits the encoding path in production.

Mistake 1 — Passing a str instead of bytes to b64encode()

Problem: b64encode() expects a bytes object. Passing a str raises a TypeError: a bytes-like object is required immediately. Fix: always call .encode("utf-8") on the string before encoding.

Before · Python

After · Python

import base64

# ❌ TypeError: a bytes-like object is required, not 'str'
webhook_secret = "wh-secret-a3f91c2b4d"
encoded = base64.b64encode(webhook_secret)  # crashes

import base64

# ✅ Encode the str to bytes first
webhook_secret = "wh-secret-a3f91c2b4d"
encoded = base64.b64encode(webhook_secret.encode("utf-8"))
# b'd2gtc2VjcmV0LWEzZjkxYzJiNGQ='

Mistake 2 — Forgetting to .decode() the bytes result

Problem: b64encode() returns bytes, not str. Embedding it directly in an f-string produces b'...' in the output, which is an invalid HTTP header value and breaks JSON serialisation. Fix: always call .decode("ascii") on the encoded result.

Before · Python

After · Python

import base64

credential = base64.b64encode(b"svc-monitor:sk-7f3a1b")
# ❌ Authorization header contains "b'c3ZjLW1vbml0b3I6c2stN2YzYTFi'"
headers = {"Authorization": f"Basic {credential}"}

import base64

credential = base64.b64encode(b"svc-monitor:sk-7f3a1b").decode("ascii")
# ✅ Authorization: Basic c3ZjLW1vbml0b3I6c2stN2YzYTFi
headers = {"Authorization": f"Basic {credential}"}

Mistake 3 — Using encodebytes() where b64encode() is needed

Problem: encodebytes() inserts a \n every 76 characters (MIME line-wrapping) and appends a trailing newline. Storing this in a JSON field, an environment variable, or a data URI embeds literal newline characters that corrupt the value downstream. Fix: use b64encode() everywhere except MIME email composition.

Before · Python

After · Python

import base64, json

cert_bytes = open("./ssl/root-ca.crt", "rb").read()
# ❌ encodebytes() adds \n every 76 chars — breaks JSON and env vars
cert_b64 = base64.encodebytes(cert_bytes).decode()
config   = json.dumps({"ca_cert": cert_b64})  # newlines inside string value

import base64, json
from pathlib import Path

cert_bytes = Path("./ssl/root-ca.crt").read_bytes()
# ✅ b64encode() produces a single unbroken string
cert_b64 = base64.b64encode(cert_bytes).decode("ascii")
config   = json.dumps({"ca_cert": cert_b64})  # clean single-line value

Mistake 4 — Decoding URL-safe Base64 with the standard decoder

Problem: URL-safe Base64 uses - and _ instead of + and /. Passing a URL-safe string to b64decode() silently produces wrong bytes for any segment that contained those characters — no exception is raised by default. Fix: use urlsafe_b64decode() for URL-safe input, or pass validate=True to detect the mismatch early.

Before · Python

After · Python

import base64

# ❌ JWT payload segment uses URL-safe Base64 (- and _)
# b64decode() silently produces wrong bytes for those characters
jwt_segment = "eyJzdWIiOiJ1c3JfN2MzYTlmMWIyZCIsInJvbGUiOiJhZG1pbiJ9"
wrong = base64.b64decode(jwt_segment)  # silently wrong if - or _ present

import base64

# ✅ Use urlsafe_b64decode() for JWT and URL-safe input
jwt_segment = "eyJzdWIiOiJ1c3JfN2MzYTlmMWIyZCIsInJvbGUiOiJhZG1pbiJ9"
padding     = 4 - len(jwt_segment) % 4
raw         = base64.urlsafe_b64decode(jwt_segment + "=" * (padding % 4))
# b'{"sub":"usr_7c3a9f1b2d","role":"admin"}'

Python Base64 Methods — Quick Comparison

Method	Input types	URL-safe chars	Padding	Line breaks	Returns	Requires install
b64encode()	bytes, bytearray, memoryview	❌ + and /	✅ = padding	❌ none	bytes	No
urlsafe_b64encode()	bytes, bytearray, memoryview	✅ - and _	✅ = padding	❌ none	bytes	No
b64encode(altchars=b"-_")	bytes, bytearray, memoryview	✅ custom 2 chars	✅ = padding	❌ none	bytes	No
encodebytes()	bytes, bytearray, memoryview	❌ + and /	✅ = padding	✅ \n every 76 chars	bytes	No
pybase64.b64encode()	bytes, bytearray, memoryview	❌ + and /	✅ = padding	❌ none	bytes	pip install
pybase64.b64encode_as_string()	bytes, bytearray, memoryview	❌ + and /	✅ = padding	❌ none	str	pip install

Choose b64encode() for the vast majority of use cases: HTTP headers, JSON fields, environment variables, and data URIs. Switch to urlsafe_b64encode() whenever the output will appear in a URL, a filename, a cookie, or a JWT segment. Use encodebytes() only when composing MIME email attachments — the line-wrapping is required by the MIME specification but will silently break everything else. Reach for pybase64 when encoding payloads above ~100 KB in a hot path.

Frequently Asked Questions

Why does base64.b64encode() return bytes instead of a string?

Python 3 strictly separates text (str) and binary data (bytes). base64.b64encode() operates on binary data and returns binary data — even though the output characters happen to be printable ASCII. This design is intentional: it forces you to be explicit about encoding boundaries. To get a str, call .decode("ascii") or .decode("utf-8") on the result. Since valid Base64 output contains only ASCII characters, both encodings produce identical results.

What is the difference between b64encode() and encodebytes() in Python?

b64encode() produces a single unbroken Base64 string — the correct choice for HTTP headers, JSON fields, data URIs, environment variables, and JWT segments. encodebytes() (formerly encodestring() in Python 2) inserts a newline character every 76 bytes and appends a trailing newline. This is the MIME line-wrapping format required for email attachments per RFC 2045. Using encodebytes() outside of email composition will embed literal newlines in your output, corrupting headers, JSON strings, and URL values.

How do I base64 encode a string with non-ASCII characters in Python?

Call .encode("utf-8") on the string to convert it to bytes, then pass those bytes to base64.b64encode(). To decode, reverse the steps: base64.b64decode(encoded), then .decode("utf-8") on the result. UTF-8 is the right choice for nearly all text — it handles every Unicode code point, including Cyrillic, CJK ideographs, Arabic, and emoji. Using .encode("ascii") on non-ASCII text will raise a UnicodeEncodeError, which is usually the correct behavior since it surfaces the encoding mismatch early.

How do I base64 encode a file in Python?

Read the file in binary mode, then call base64.b64encode() on the bytes. The simplest one-liner is: encoded = base64.b64encode(Path("file.bin").read_bytes()).decode("ascii"). For large files (above ~50–100 MB), avoid loading the entire file into memory. Instead, read in chunks of a size that is a multiple of 3 bytes (e.g., 3 × 1024 × 256 = 786,432 bytes) and encode each chunk separately — processing chunk sizes that are multiples of 3 avoids spurious = padding characters appearing in the middle of the output.

Why does Python's urlsafe_b64encode() still include = padding? JWT doesn't use it.

The stdlib follows the RFC 4648 §5 specification, which keeps = padding. JWT (RFC 7519) defines its own Base64url encoding that strips padding entirely. The mismatch is a deliberate spec decision: RFC 4648 padding makes the string self-describing (you can always determine the original byte length), while JWT strips it to reduce token length. To match JWT format, call .rstrip(b"=") on the encoded output before decoding with .decode("ascii"). When decoding, add back the correct padding: padding = 4 - len(segment) % 4; padded = segment + "=" * (padding % 4).

Is there a way to validate that a string is valid Base64 before decoding it?

Pass validate=True to base64.b64decode(). With this flag, any character outside the standard Base64 alphabet (A–Z, a–z, 0–9, +, /, =) raises a binascii.Error. Without validate=True, b64decode() silently ignores invalid characters, which can mask corrupted input. For URL-safe Base64, there is no validate parameter in urlsafe_b64decode() — you can validate manually with a regex: import re; bool(re.fullmatch(r"[A-Za-z0-9_-]+=*", segment)). Always validate input from untrusted external sources before decoding.

For a one-click encode or decode without writing any Python, paste your string or file directly into the Base64 Encoder — it handles standard and URL-safe modes instantly in your browser, with no setup required.

Base64 Decode

Decode any Base64 string back to plain text — useful for inspecting encoded API responses, JWT payloads, or certificate blobs stored in environment variables.

URL Encode

Percent-encode strings for safe embedding in URLs — often used alongside Base64 when building query parameters, OAuth signatures, or webhook callback URLs.

JWT Decoder

Decode and inspect JWT tokens — each of the three dot-separated segments is URL-safe Base64, and this tool decodes all three and displays the claims.

JSON Formatter

Pretty-print JSON payloads decoded from Base64 — useful when debugging API responses, config blobs, or JWT payloads stored as encoded strings.

Also available in:JavaScript Java

Maria SantosBackend Developer

Maria is a backend developer specialising in Python and API integration. She has broad experience with data pipelines, serialisation formats, and building reliable server-side services. She is an active member of the Python community and enjoys writing practical, example-driven guides that help developers solve real problems without unnecessary theory.

Priya SharmaTechnical Reviewer

Priya is a data scientist and machine learning engineer who has worked across the full Python data stack — from raw data ingestion and cleaning to model deployment and monitoring. She is passionate about reproducible research, Jupyter-based workflows, and the practical engineering side of ML. She writes about NumPy, Pandas, data serialisation, and the Python patterns that make data pipelines reliable at scale.

Base64 Encode Python — b64encode() Guide

What is Base64 Encoding?

base64.b64encode() — Standard Encoding Guide with Examples

Minimal working example

Extended example — sort_keys, nested objects, round-trip decode

Encoding Non-ASCII and Unicode Strings in Python

base64 Module — Functions Reference

URL-Safe Base64 — urlsafe_b64encode() for JWTs and Query Parameters

Encoding a JWT payload segment

Encoding Files and API Responses in Python

Reading a file from disk and encoding it

Encoding an HTTP API response for debugging

How to Base64 Encode an Image File in Python

Working with Large Files — Chunked Base64 Encoding

Streaming encode to a file (no full-file memory load)

Encoding a directory of binary assets (NDJSON output)

Command-Line Base64 Encoding with Python

High-Performance Alternative: pybase64

Terminal Output with Syntax Highlighting

Common Mistakes

Mistake 1 — Passing a str instead of bytes to b64encode()

Mistake 2 — Forgetting to .decode() the bytes result

Mistake 3 — Using encodebytes() where b64encode() is needed

Mistake 4 — Decoding URL-safe Base64 with the standard decoder

Python Base64 Methods — Quick Comparison

Frequently Asked Questions

Related Tools