Кодування Base64 в Python: b64encode та приклади
Використовуйте безкоштовний 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.
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+).
Мінімальний робочий приклад
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 декодування
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-fullb64decode() за замовчуванням поблажливий — він мовчки ігнорує недопустимі символи, включаючи пробіли та переноси рядків. Передайте validate=True, щоб викликати binascii.Error при наявності будь-якого символу поза алфавітом Base64. Використовуйте це при декодуванні недовірених даних із зовнішніх систем.Кодування не-ASCII та Unicode рядків у Python
Рядки Python 3 за замовчуванням є Unicode. Модуль base64 працює з bytes, а не з str — тому необхідно спочатку закодувати рядок у байти. Вибір кодування важливий: UTF-8 обробляє кожну кодову точку Unicode і є правильним значенням за замовчуванням майже для всіх випадків.
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 надає кілька функцій кодування. Ось повний довідник тих, з якими ви зустрінетеся на практиці:
| Функція | Вхід | Повертає | Опис |
|---|---|---|---|
| b64encode(s, altchars=None) | bytes | bytes | Стандартний Base64 (RFC 4648 §4). altchars замінює символи + та / двома власними байтами. |
| b64decode(s, altchars=None, validate=False) | bytes | str | bytes | Декодує стандартний Base64. validate=True викликає binascii.Error при недопустимих символах. |
| urlsafe_b64encode(s) | bytes | bytes | URL-безпечний Base64 (RFC 4648 §5). Використовує - та _ замість + та /. Зберігає паддинг =. |
| urlsafe_b64decode(s) | bytes | str | bytes | Декодує URL-безпечний Base64. Приймає як доповнений, так і недоповнений ввід. |
| encodebytes(s) | bytes | bytes | MIME Base64: вставляє \n кожні 76 символів і додає завершальний \n. Лише для email/MIME. |
| decodebytes(s) | bytes | bytes | Декодує MIME Base64. Ігнорує пробільні символи та вбудовані переноси рядків. |
| b16encode(s) | bytes | bytes | Hex-кодування (Base16). Кожен байт стає двома символами верхнього регістру hex. Без паддингу. |
| b32encode(s) | bytes | bytes | Base32-кодування. Використовує 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-даних
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-engineerurlsafe_b64decode() приймає як доповнений, так і недоповнений ввід починаючи з Python 3.x, але лише якщо символи є URL-безпечними (- та _). Ніколи не передавайте стандартний рядок Base64 (з + або /) до urlsafe_b64decode — невідповідні символи спричинять приховане пошкодження даних або binascii.Error.Кодування файлів та відповідей API у Python
У production-коді Base64-кодування найчастіше застосовується до файлів, які потрібно передати, та до відповідей зовнішніх API з бінарним вмістом. Обидва сценарії вимагають ретельної обробки межі bytes.
Читання файлу з диска та його кодування
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-відповіді для налагодження
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.
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...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 місце, кодувальник додає паддинг = посередині потоку, роблячи конкатенований вивід недійсним.
Потокове кодування у файл (без завантаження всього файлу в пам'ять)
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)
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 може бути недоступна.
# ── 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.
pip install pybase64
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.
pip install rich
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") на рядку перед кодуванням.
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") на закодованому результаті.
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-пошти.
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 для раннього виявлення невідповідності.
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 | ❌ + та / | ✅ паддинг = | ❌ немає | bytes | pip install |
| pybase64.b64encode_as_string() | bytes, bytearray, memoryview | ❌ + та / | ✅ паддинг = | ❌ немає | str | pip install |
Використовуйте b64encode() для переважної більшості випадків: HTTP-заголовки, JSON-поля, змінні оточення та data URI. Переходьте на urlsafe_b64encode(), коли вивід з'являтиметься в URL, імені файлу, cookie або JWT-сегменті. Використовуйте encodebytes() лише при складанні MIME-вкладень для email — перенос рядків вимагається специфікацією MIME, але мовчки зламає все інше. Звертайтеся до pybase64, коли кодуєте дані обсягом понад ~100 КБ у гарячому шляху.
Часті запитання
Пов'язані інструменти
Для кодування або декодування одним кліком без написання Python-коду вставте рядок або файл прямо до Base64 Encoder — він обробляє стандартний та URL-safe режими миттєво у браузері без жодного налаштування.
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 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.