Кодування Base64 в Python: b64encode та приклади

·Backend Developer·ПеревіреноPriya Sharma·Опубліковано

Використовуйте безкоштовний Base64 Encode Online прямо в браузері — без встановлення.

Спробувати Base64 Encode Online онлайн →

Коли ви розробляєте Python-сервіси, що передають облікові дані в заголовках HTTP Basic Auth, вбудовують бінарні ресурси у відповіді API або зберігають TLS-сертифікати у змінних оточення, вам регулярно доводиться писати код для Base64-кодування на Python. Python постачає модуль base64 у стандартній бібліотеці — pip install не потрібен — але різниця між байтами та рядками, а також між b64encode, urlsafe_b64encode та encodebytes спотикає розробників частіше, ніж можна очікувати. Для швидкого кодування без написання коду Base64 Encoder від ToolDeck впорається миттєво прямо у браузері. Цей посібник охоплює повний stdlib API, URL-безпечне кодування для JWT, сценарії з файлами та відповідями API, CLI-команди, високопродуктивну альтернативу та чотири помилки, які я найчастіше зустрічаю під час code review.

  • base64.b64encode() очікує bytes, а не str — завжди викликайте .encode("utf-8") на вхідному рядку перед передачею
  • Повернуте значення теж bytes — викличте .decode("utf-8") або .decode("ascii"), щоб отримати звичайний str для вбудовування в JSON або HTTP-заголовки
  • base64.urlsafe_b64encode() замінює + → - та / → _, але зберігає паддинг = — вручну видаліть його через .rstrip("=") для JWT-сегментів
  • base64.encodebytes() вставляє \n кожні 76 символів (формат MIME) — ніколи не використовуйте його для data URI, JSON-полів або змінних оточення
  • pybase64 (розширення на C, сумісний API) кодує у 2–10× швидше stdlib; виправданий для високонавантажених сервісів з великими даними

Що таке Base64-кодування?

Base64 перетворює довільні бінарні дані на рядок із 64 друкованих ASCII-символів: A–Z, a–z, 0–9, + та /. Кожні 3 вхідних байти відображаються рівно у 4 символи Base64. Якщо довжина входу не кратна 3, додаються один або два символи = паддингу. Закодований вивід завжди приблизно на 33% більший за оригінал.

Base64 — це не шифрування: він не забезпечує жодної конфіденційності. Його призначення — безпека транспорту: багато протоколів і систем зберігання розроблені для 7-бітного ASCII-тексту та не можуть безпечно переносити довільні бінарні байти. Base64 усуває цей розрив. Типові застосування в Python: заголовки HTTP Basic Auth, data URI для вбудовування зображень в HTML або CSS, сегменти JWT-токенів, вкладення MIME-пошти та передача бінарних даних через змінні оточення або JSON API.

Before · text
After · text
deploy-svc:sk-prod-9f2a1c3e8b4d
ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==

base64.b64encode() — Посібник зі стандартного кодування з прикладами

base64.b64encode(s, altchars=None) — основна функція кодування в stdlib Python. Вона знаходиться в модулі base64, що постачається з кожною інсталяцією Python. Функція приймає об'єкт bytes і повертає об'єкт bytes, що містить ASCII-представлення Base64. У цьому посібнику передбачається використання Python 3.x (3.6+).

Мінімальний робочий приклад

Python 3.6+
import base64

# Кодування пари облікових даних API для заголовка HTTP Basic Auth
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}")
# Значення заголовка: Basic ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==

Розширений приклад — sort_keys, вкладені об'єкти, round-trip декодування

Python 3.6+
import base64
import json

# Кодування структурованої конфігурації сервера для змінної оточення
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...

# Декодування та 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
Примітка:b64decode() за замовчуванням поблажливий — він мовчки ігнорує недопустимі символи, включаючи пробіли та переноси рядків. Передайте validate=True, щоб викликати binascii.Error при наявності будь-якого символу поза алфавітом Base64. Використовуйте це при декодуванні недовірених даних із зовнішніх систем.

Кодування не-ASCII та Unicode рядків у Python

Рядки Python 3 за замовчуванням є Unicode. Модуль base64 працює з bytes, а не з str — тому необхідно спочатку закодувати рядок у байти. Вибір кодування важливий: UTF-8 обробляє кожну кодову точку Unicode і є правильним значенням за замовчуванням майже для всіх випадків.

Python 3.6+
import base64

# Кодування багатомовного контенту — відображувані імена користувачів міжнародної платформи
user_names = [
    "Олексій Коваленко",    # Кирилиця — U+0410 і вище
    "田中太郎",              # Ієрогліфи CJK — 3 байти кожен у UTF-8
    "Carlos Mendoza",        # ASCII — 1 байт на символ
    "Ірина Шевченко",        # Кирилиця — ще один приклад
]

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

    print(f"Оригінал : {name}")
    print(f"Закодовано: {encoded}")
    print(f"Туди-назад: {decoded}")
    print(f"Збіг     : {name == decoded}")
    print()

# Оригінал : Олексій Коваленко
# Закодовано: 0J7Qu9C10LrRgdGW0Lkg0JrQvtCy0LDQu9C10L3QutC+
# Туди-назад: Олексій Коваленко
# Збіг     : True
Примітка:Якщо потрібно переконатися в правильності кодування конкретного рядка, вставте вивід Base64 прямо до Base64 Encoder від ToolDeck — він декодує в реальному часі та показує точне UTF-8 байтове представлення. Зручно при налагодженні кириличних, CJK або emoji-рядків у даних.

Модуль base64 — Довідник функцій

Модуль base64 надає кілька функцій кодування. Ось повний довідник тих, з якими ви зустрінетеся на практиці:

ФункціяВхідПовертаєОпис
b64encode(s, altchars=None)bytesbytesСтандартний Base64 (RFC 4648 §4). altchars замінює символи + та / двома власними байтами.
b64decode(s, altchars=None, validate=False)bytes | strbytesДекодує стандартний Base64. validate=True викликає binascii.Error при недопустимих символах.
urlsafe_b64encode(s)bytesbytesURL-безпечний Base64 (RFC 4648 §5). Використовує - та _ замість + та /. Зберігає паддинг =.
urlsafe_b64decode(s)bytes | strbytesДекодує URL-безпечний Base64. Приймає як доповнений, так і недоповнений ввід.
encodebytes(s)bytesbytesMIME Base64: вставляє \n кожні 76 символів і додає завершальний \n. Лише для email/MIME.
decodebytes(s)bytesbytesДекодує MIME Base64. Ігнорує пробільні символи та вбудовані переноси рядків.
b16encode(s)bytesbytesHex-кодування (Base16). Кожен байт стає двома символами верхнього регістру hex. Без паддингу.
b32encode(s)bytesbytesBase32-кодування. Використовує A–Z та 2–7. Більший вивід, ніж Base64; використовується в TOTP-секретах.

Параметр altchars у b64encode приймає 2-байтовий об'єкт, що замінює символи + та /. Передача altchars=b'-_' дає вивід, ідентичний urlsafe_b64encode, але дозволяє керувати паддингом окремо.

URL-безпечний Base64 — urlsafe_b64encode() для JWT та параметрів запиту

Стандартний Base64 використовує + та / — обидва є зарезервованими символами в URL. Символ + у рядку запиту декодується як пробіл, а / є роздільником шляху. Коли закодоване значення з'являється в URL, імені файлу або cookie, потрібен URL-безпечний варіант: urlsafe_b64encode() замінює - на + та _ на /.

JWT використовують URL-безпечний Base64 без паддингу для всіх трьох сегментів (заголовок, дані, підпис). Паддинг потрібно видаляти вручну — stdlib Python його зберігає.

Кодування сегмента JWT-даних

Python 3.6+
import base64
import json

def encode_jwt_segment(data: dict) -> str:
    """Кодує dict у URL-безпечний рядок Base64 без паддингу (формат JWT)."""
    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:
    """Декодує URL-безпечний JWT-сегмент Base64 (обробляє відсутній паддинг)."""
    # Відновлюємо паддинг: Base64 вимагає довжину, кратну 4
    padding  = 4 - len(segment) % 4
    padded   = segment + ("=" * (padding % 4))
    raw      = base64.urlsafe_b64decode(padded)
    return json.loads(raw)

# Створюємо заголовок та дані JWT
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...

# Перевіряємо round-trip
restored = decode_jwt_segment(payload_segment)
print(restored["role"])  # data-engineer
Примітка:urlsafe_b64decode() приймає як доповнений, так і недоповнений ввід починаючи з Python 3.x, але лише якщо символи є URL-безпечними (- та _). Ніколи не передавайте стандартний рядок Base64 (з + або /) до urlsafe_b64decode — невідповідні символи спричинять приховане пошкодження даних або binascii.Error.

Кодування файлів та відповідей API у Python

У production-коді Base64-кодування найчастіше застосовується до файлів, які потрібно передати, та до відповідей зовнішніх API з бінарним вмістом. Обидва сценарії вимагають ретельної обробки межі bytes.

Читання файлу з диска та його кодування

Python 3.6+
import base64
import json
from pathlib import Path

def encode_file_to_base64(file_path: str) -> str:
    """Читає бінарний файл і повертає його Base64-представлення."""
    try:
        raw_bytes = Path(file_path).read_bytes()
        return base64.b64encode(raw_bytes).decode("ascii")
    except FileNotFoundError:
        raise FileNotFoundError(f"Файл не знайдено: {file_path}")
    except PermissionError:
        raise PermissionError(f"Доступ заборонено при читанні: {file_path}")

# Прикріплюємо TLS-сертифікат до маніфесту деплою
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",
    },
}

# Записуємо маніфест — сертифікат безпечно вбудовано як рядок
with open("./dist/deployment-manifest.json", "w") as f:
    json.dump(deployment_manifest, f, indent=2)

print(f"Сертифікат закодовано: {len(cert_b64)} символів")

Кодування HTTP API-відповіді для налагодження

Python 3.6+
import base64
import requests  # pip install requests

def fetch_and_encode_binary(url: str, headers: dict | None = None) -> str:
    """Завантажує бінарний ресурс з API і повертає його у вигляді Base64."""
    response = requests.get(url, headers=headers or {}, timeout=10)
    response.raise_for_status()  # викликає HTTPError для 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    : {len(response.content):,} байт")
    print(f"Розмір encoded: {len(encoded):,} символів")
    return encoded

# Приклад: завантажуємо підписаний PDF-рахунок із внутрішнього API білінгу
invoice_b64 = fetch_and_encode_binary(
    "https://billing.internal/api/v2/invoices/INV-2026-0042/pdf",
    headers={"Authorization": "Bearer eyJhbGc..."},
)

# Прикріплюємо до повідомлення
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 готовий: {len(str(notification)):,} символів")

Як закодувати файл зображення в Base64 на Python

Кодування зображення в Base64 та вбудовування його у вигляді data URI — стандартний підхід для HTML-шаблонів email, генерації PDF та самодостатніх HTML-знімків. Браузер інтерпретує закодований рядок напряму — окремий запит зображення не потрібен. Той самий шаблон працює для будь-якого бінарного формату: PNG, JPEG, SVG, WebP або PDF.

Python 3.6+
import base64
import mimetypes
from pathlib import Path

def image_to_data_uri(image_path: str) -> str:
    """Перетворює файл зображення на data URI Base64 для вбудовування в HTML."""
    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}"

# Вбудовуємо зображення продуктів у HTML-шаблон email
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 починається з: {hero_uri[:60]}...")
# data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAwAAAAA...
Примітка:Для SVG-файлів data URI з URL-кодуванням (data:image/svg+xml,{encoded}) часто менший, ніж Base64, тому що SVG текстовий і Base64 збільшує розмір на ~33%. Використовуйте Base64 для растрових форматів (PNG, JPEG, WebP) та URL-кодування для SVG.

Робота з великими файлами — кодування Base64 по чанках

Завантаження цілого файлу в пам'ять через Path.read_bytes() нормально для файлів до ~50 МБ. При перевищенні цього порогу пікове споживання пам'яті стає значним — файл 200 МБ потребує ~200 МБ для вихідних байтів плюс ~267 МБ для виводу Base64, загалом ~467 МБ в одному процесі. Для великих файлів читайте та кодуйте по чанках.

Критичне обмеження: розмір чанку повинен бути кратним 3 байтам. Base64 кодує 3 вхідних байти рівно у 4 вихідних символи. Якщо межа чанку припадає на некратне 3 місце, кодувальник додає паддинг = посередині потоку, роблячи конкатенований вивід недійсним.

Потокове кодування у файл (без завантаження всього файлу в пам'ять)

Python 3.6+
import base64
from pathlib import Path

CHUNK_SIZE = 3 * 1024 * 256  # 786 432 байти — кратно 3, ~768 КБ на чанк

def encode_large_file(input_path: str, output_path: str) -> int:
    """
    Кодує великий бінарний файл у Base64 без повного завантаження в пам'ять.
    Повертає кількість записаних символів Base64.
    """
    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

# Кодуємо 300 МБ відео продукту для маніфесту доставки ресурсів
chars_written = encode_large_file(
    "./uploads/product-demo-4k.mp4",
    "./dist/product-demo-4k.b64",
)
print(f"Закодовано: {chars_written:,} символів Base64")
# Закодовано: 407 374 184 символи Base64

Кодування директорії бінарних ресурсів (вивід NDJSON)

Python 3.6+
import base64
import json
from pathlib import Path

def encode_assets_to_ndjson(asset_dir: str, output_path: str) -> int:
    """
    Кодує всі бінарні файли в директорії у NDJSON-маніфест.
    Кожен рядок — JSON-об'єкт: {"path": "...", "mime": "...", "data": "<base64>"}
    Повертає кількість оброблених файлів.
    """
    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"Закодовано {processed} файлів у NDJSON-пакет ресурсів")
Примітка:Переходьте від read_bytes() до читання по чанках, коли вхідний файл перевищує ~50–100 МБ або коли ваш сервіс обробляє багато файлів одночасно і навантаження по пам'яті стає критичним. Для файлів до 50 МБ однорядник b64encode(path.read_bytes()).decode() швидший і простіший у розумінні.

Base64-кодування в командному рядку за допомогою Python

Python постачає CLI-інтерфейс для модуля base64 — додаткові інструменти не потрібні. Він працює кросплатформно, що робить його корисним у CI-пайплайнах та Windows-середовищах, де системна команда base64 може бути недоступна.

bash
# ── python -m base64 ───────────────────────────────────────────────────
# Кодування рядка (stdin через pipe)
echo -n "deploy-svc:sk-prod-9f2a1c3e8b4d" | python3 -m base64
# ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==

# Кодування файлу
python3 -m base64 ./ssl/service-client.crt

# Декодування рядка Base64
echo "ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==" | python3 -m base64 -d

# Декодування файлу Base64 назад у бінарний
python3 -m base64 -d ./dist/service-client.b64 > ./restored.crt

# ── Однорядник Python — кросплатформно, працює на Windows ────────────────
# Кодування рядка
python3 -c "import base64,sys; print(base64.b64encode(sys.argv[1].encode()).decode())" "my-secret"
# bXktc2VjcmV0

# URL-safe кодування (без паддингу)
python3 -c "import base64,sys; print(base64.urlsafe_b64encode(sys.argv[1].encode()).rstrip(b'=').decode())" "my-secret"
# bXktc2VjcmV0

# Кодування файлу в рядок (результат на stdout)
python3 -c "import base64,sys; print(base64.b64encode(open(sys.argv[1],'rb').read()).decode())" ./config.json
Примітка:На відміну від системної команди base64 в macOS, python -m base64 за замовчуванням не переносить вивід на 76 символах. Вивід — один безперервний рядок, що і потрібно для змінних оточення, JSON-полів та HTTP-заголовків. Використовуйте як замінник системному base64 на будь-якій ОС.

Високопродуктивна альтернатива: pybase64

Модуль base64 зі stdlib Python реалізований на чистому Python (з тонким шаром C у CPython). Для сервісів, що кодують великі дані з високою пропускною здатністю — пайплайни обробки зображень, задачі масового експорту, приймання телеметрії в реальному часі — pybase64 є сумісною заміною, заснованою на libbase64 — SIMD-прискореній бібліотеці C. Тести продуктивності показують покращення пропускної здатності у 2–10× залежно від розміру даних та архітектури CPU.

bash
pip install pybase64
Python 3.6+
import pybase64
import time

# pybase64 — замінник stdlib: ті самі сигнатури функцій
sample_payload = b"x" * (1024 * 1024)  # 1 МБ бінарних даних

# Стандартне кодування — ідентичний вивід base64.b64encode()
encoded = pybase64.b64encode(sample_payload)
decoded = pybase64.b64decode(encoded)
assert decoded == sample_payload

# URL-safe кодування — ідентичний вивід base64.urlsafe_b64encode()
url_safe = pybase64.urlsafe_b64encode(sample_payload)

# b64encode_as_string() повертає str напряму — виклик .decode() не потрібен
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...

# Порівняння пропускної здатності (приблизно, залежить від заліза)
# stdlib  base64.b64encode(1 МБ):   ~80 МБ/с
# pybase64.b64encode(1 МБ):         ~800 МБ/с (шлях SIMD на CPU з AVX2)

Переходьте на pybase64, коли профілювання показує Base64-кодування як вузьке місце, або коли ви багаторазово кодуєте дані обсягом понад ~100 КБ. Для одноразового кодування невеликих рядків (облікові дані, токени) stdlib достатньо швидкий і не потребує залежностей.

Вивід у термінал з підсвічуванням синтаксису

При налагодженні Base64-закодованих даних у терміналі — особливо JSON-конфігурацій або вмісту JWT — бібліотека rich дає підсвічений синтаксис з відступами, який набагато зручніший для читання, ніж сирий дамп. Особливо корисна в CLI-інструментах, налагоджувальних скриптах та сесіях REPL.

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 = "Декодовані дані") -> None:
    """Декодує рядок Base64, розбирає як JSON і виводить з підсвічуванням синтаксису."""
    raw_bytes = base64.b64decode(encoded + "==")  # допустимий паддинг
    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:
        # Не JSON — виводимо сирий текст
        console.rule(f"[bold yellow]{label} (сирий текст)")
        rprint(raw_bytes.decode("utf-8", errors="replace"))

# Інспектуємо сегмент JWT-даних із невдалого запиту аутентифікації
jwt_payload_segment = "eyJzdWIiOiJ1c3JfN2MzYTlmMWIyZCIsInJvbGUiOiJkYXRhLWVuZ2luZWVyIiwiZXhwIjoxNzQxOTEwNDAwfQ"
decode_and_pretty_print(jwt_payload_segment, "JWT Payload")
Примітка:Використовуйте вивід rich лише для відображення в терміналі — при налагодженні, логуванні в stdout або інтерактивних CLI-інструментах. Ніколи не використовуйте його для запису Base64 у файли, повернення з API-ендпоінтів або зберігання у змінних оточення, оскільки rich додає ANSI-escape-коди, що псують дані.

Типові помилки

Я переглянув багато Python-кодових баз із Base64-кодуванням, і ці чотири помилки зустрічаються регулярно — часто залишаються непоміченими, поки не-ASCII ввід або бінарний файл не потрапить на шлях кодування у production.

Помилка 1 — Передача str замість bytes у b64encode()

Проблема: b64encode() очікує об'єкт bytes. Передача str негайно викликає TypeError: a bytes-like object is required. Рішення: завжди викликайте .encode("utf-8") на рядку перед кодуванням.

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)  # падає
import base64

# ✅ Спочатку кодуємо str у bytes
webhook_secret = "wh-secret-a3f91c2b4d"
encoded = base64.b64encode(webhook_secret.encode("utf-8"))
# b'd2gtc2VjcmV0LWEzZjkxYzJiNGQ='

Помилка 2 — Забути викликати .decode() на результаті bytes

Проблема: b64encode() повертає bytes, а не str. Вбудовування напряму в f-рядок дає b'...' у виводі — недопустиме значення HTTP-заголовка, що також ламає серіалізацію JSON. Рішення: завжди викликайте .decode("ascii") на закодованому результаті.

Before · Python
After · Python
import base64

credential = base64.b64encode(b"svc-monitor:sk-7f3a1b")
# ❌ Заголовок Authorization містить "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}"}

Помилка 3 — Використання encodebytes() замість b64encode()

Проблема: encodebytes() вставляє \n кожні 76 символів (MIME-перенос рядків) і додає завершальний перенос. Зберігання цього в JSON-полі, змінній оточення або data URI вбудовує буквальні символи переносу рядка, що псують значення далі по ланцюгу. Рішення: використовуйте b64encode() скрізь, крім складання MIME-пошти.

Before · Python
After · Python
import base64, json

cert_bytes = open("./ssl/root-ca.crt", "rb").read()
# ❌ encodebytes() додає \n кожні 76 символів — ламає JSON і змінні оточення
cert_b64 = base64.encodebytes(cert_bytes).decode()
config   = json.dumps({"ca_cert": cert_b64})  # переноси рядків всередині значення
import base64, json
from pathlib import Path

cert_bytes = Path("./ssl/root-ca.crt").read_bytes()
# ✅ b64encode() створює єдиний безперервний рядок
cert_b64 = base64.b64encode(cert_bytes).decode("ascii")
config   = json.dumps({"ca_cert": cert_b64})  # чисте однорядкове значення

Помилка 4 — Декодування URL-safe Base64 стандартним декодером

Проблема: URL-safe Base64 використовує - та _ замість + та /. Передача URL-safe рядка до b64decode() мовчки виробляє невірні байти для будь-якого сегмента з цими символами — виняток за замовчуванням не викликається. Рішення: використовуйте urlsafe_b64decode() для URL-safe вводу або передавайте validate=True для раннього виявлення невідповідності.

Before · Python
After · Python
import base64

# ❌ JWT payload-сегмент використовує URL-safe Base64 (- та _)
# b64decode() мовчки виробляє невірні байти для таких символів
jwt_segment = "eyJzdWIiOiJ1c3JfN2MzYTlmMWIyZCIsInJvbGUiOiJhZG1pbiJ9"
wrong = base64.b64decode(jwt_segment)  # мовчки невірно при наявності - або _
import base64

# ✅ Використовуємо urlsafe_b64decode() для JWT та URL-safe вводу
jwt_segment = "eyJzdWIiOiJ1c3JfN2MzYTlmMWIyZCIsInJvbGUiOiJhZG1pbiJ9"
padding     = 4 - len(jwt_segment) % 4
raw         = base64.urlsafe_b64decode(jwt_segment + "=" * (padding % 4))
# b'{"sub":"usr_7c3a9f1b2d","role":"admin"}'

Методи Base64 у Python — Швидке порівняння

МетодТипи вводуURL-safe символиПаддингПереноси рядківПовертаєПотребує встановлення
b64encode()bytes, bytearray, memoryview❌ + та /✅ паддинг =❌ немаєbytesНі
urlsafe_b64encode()bytes, bytearray, memoryview✅ - та _✅ паддинг =❌ немаєbytesНі
b64encode(altchars=b"-_")bytes, bytearray, memoryview✅ 2 власних символи✅ паддинг =❌ немаєbytesНі
encodebytes()bytes, bytearray, memoryview❌ + та /✅ паддинг =✅ \n кожні 76 символівbytesНі
pybase64.b64encode()bytes, bytearray, memoryview❌ + та /✅ паддинг =❌ немаєbytespip install
pybase64.b64encode_as_string()bytes, bytearray, memoryview❌ + та /✅ паддинг =❌ немаєstrpip install

Використовуйте b64encode() для переважної більшості випадків: HTTP-заголовки, JSON-поля, змінні оточення та data URI. Переходьте на urlsafe_b64encode(), коли вивід з'являтиметься в URL, імені файлу, cookie або JWT-сегменті. Використовуйте encodebytes() лише при складанні MIME-вкладень для email — перенос рядків вимагається специфікацією MIME, але мовчки зламає все інше. Звертайтеся до pybase64, коли кодуєте дані обсягом понад ~100 КБ у гарячому шляху.

Часті запитання

Чому base64.b64encode() повертає bytes, а не рядок?
Python 3 суворо розділяє текст (str) та бінарні дані (bytes). base64.b64encode() працює з бінарними даними та повертає бінарні дані — навіть попри те, що вихідні символи є друкованим ASCII. Це навмисне рішення: воно змушує явно визначати межі кодування. Щоб отримати str, викличте .decode("ascii") або .decode("utf-8") на результаті. Оскільки допустимий вивід Base64 містить лише ASCII-символи, обидва кодування дають ідентичний результат.
У чому різниця між b64encode() та encodebytes() у Python?
b64encode() створює єдиний безперервний рядок Base64 — правильний вибір для HTTP-заголовків, JSON-полів, data URI, змінних оточення та JWT-сегментів. encodebytes() (раніше encodestring() у Python 2) вставляє символ переносу рядка кожні 76 байт і додає завершальний перенос. Це формат MIME-переносу рядків, необхідний для вкладень email згідно з RFC 2045. Використання encodebytes() поза складанням email вбудує буквальні переноси рядків у вивід, псуючи заголовки, JSON-рядки та URL-значення.
Як закодувати в Base64 рядок з не-ASCII символами у Python?
Викличте .encode("utf-8") на рядку, щоб перетворити його на bytes, а потім передайте ці bytes до base64.b64encode(). Для декодування виконайте кроки у зворотному порядку: base64.b64decode(encoded), потім .decode("utf-8") на результаті. UTF-8 — правильний вибір майже для всього тексту: він обробляє кожну кодову точку Unicode, включаючи кирилицю, ієрогліфи CJK, арабську та emoji. Використання .encode("ascii") на не-ASCII тексті викличе UnicodeEncodeError, що зазвичай є правильною поведінкою, оскільки виявляє невідповідність кодування на ранньому етапі.
Як закодувати файл у Base64 на Python?
Прочитайте файл у бінарному режимі, потім викличте base64.b64encode() на байтах. Найпростіший однорядник: encoded = base64.b64encode(Path("file.bin").read_bytes()).decode("ascii"). Для великих файлів (понад ~50–100 МБ) уникайте завантаження всього файлу в пам'ять. Натомість читайте по чанках розміром, кратним 3 байтам (наприклад, 3 × 1024 × 256 = 786 432 байти) та кодуйте кожен чанк окремо — обробка чанків розміром, кратним 3, запобігає появі паддингу = посередині виводу.
Чому urlsafe_b64encode() у Python все одно включає паддинг =? JWT його не використовує.
Stdlib дотримується специфікації RFC 4648 §5, яка зберігає паддинг =. JWT (RFC 7519) визначає власне кодування Base64url, що повністю прибирає паддинг. Невідповідність є навмисним рішенням специфікації: паддинг RFC 4648 робить рядок самодостатнім (завжди можна визначити вихідну довжину в байтах), тоді як JWT прибирає його для зменшення довжини токена. Для відповідності формату JWT викличте .rstrip(b"=") на закодованому виводі перед декодуванням з .decode("ascii"). При декодуванні додайте правильний паддинг: padding = 4 - len(segment) % 4; padded = segment + "=" * (padding % 4).
Чи можна перевірити, чи є рядок допустимим Base64 перед декодуванням?
Передайте validate=True до base64.b64decode(). З цим прапором будь-який символ поза алфавітом стандартного Base64 (A–Z, a–z, 0–9, +, /, =) викликає binascii.Error. Без validate=True b64decode() мовчки ігнорує недопустимі символи, що може приховати пошкоджений ввід. Для URL-safe Base64 параметра validate в urlsafe_b64decode() немає — можна перевірити вручну за допомогою regex: import re; bool(re.fullmatch(r"[A-Za-z0-9_-]+=*", segment)). Завжди перевіряйте ввід із недовірених зовнішніх джерел перед декодуванням.

Пов'язані інструменти

Для кодування або декодування одним кліком без написання Python-коду вставте рядок або файл прямо до Base64 Encoder — він обробляє стандартний та URL-safe режими миттєво у браузері без жодного налаштування.

Також доступно на:JavaScriptJava
MS
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.

PS
Priya SharmaТехнічний рецензент

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.