Base64 Encode Python — Guide b64encode()

·Backend Developer·Révisé parPriya Sharma·Publié

Utilisez le Encodeur Base64 en Ligne gratuit directement dans votre navigateur — sans installation.

Essayer Encodeur Base64 en Ligne en ligne →

Lorsque vous développez des services Python qui transmettent des identifiants dans des en-têtes HTTP Basic Auth, intègrent des ressources binaires dans des réponses d'API ou stockent des certificats TLS dans des variables d'environnement, vous finissez par écrire régulièrement du code base64 encode Python. Python fournit le module base64 dans sa bibliothèque standard — sans pip install — mais la distinction bytes/string et la différence entre b64encode, urlsafe_b64encode et encodebytespiègent les développeurs plus souvent qu'on ne le penserait. Pour un encodage rapide sans écrire de code, l'Encodeur Base64 de ToolDeck le fait instantanément dans le navigateur. Ce guide couvre l'API complète de la stdlib, l'encodage URL-safe pour les JWT, les scénarios de fichiers et de réponses API, les raccourcis CLI, une alternative haute performance et les quatre erreurs les plus courantes que je rencontre lors des revues de code.

  • base64.b64encode() attend des bytes, pas une str — appelez toujours .encode("utf-8") sur la chaîne d'entrée avant de la passer
  • La valeur de retour est aussi des bytes — appelez .decode("utf-8") ou .decode("ascii") pour obtenir une str que vous pouvez intégrer dans du JSON ou des en-têtes HTTP
  • base64.urlsafe_b64encode() remplace + → - et / → _ mais conserve le rembourrage = — supprimez-le manuellement avec .rstrip("=") pour les segments JWT
  • base64.encodebytes() insère un \n tous les 76 caractères (format MIME) — ne l'utilisez jamais pour les URI de données, les champs JSON ou les variables d'environnement
  • pybase64 (extension C, API compatible) encode 2 à 10 fois plus vite que la stdlib ; utile pour les services à haut débit traitant de grandes charges utiles

Qu'est-ce que l'encodage Base64 ?

Base64 convertit des données binaires arbitraires en une chaîne composée de 64 caractères ASCII imprimables : A–Z, a–z, 0–9, + et /. Chaque tranche de 3 octets d'entrée correspond exactement à 4 caractères Base64. Si la longueur de l'entrée n'est pas un multiple de 3, un ou deux caractères de rembourrage =sont ajoutés. La sortie encodée est toujours environ 33 % plus grande que l'original.

Base64 n'est pasdu chiffrement — il ne fournit aucune confidentialité. Son objectif est la sécurité du transport : de nombreux protocoles et systèmes de stockage ont été conçus pour du texte ASCII 7 bits et ne peuvent pas transporter en toute sécurité des octets binaires arbitraires. Base64 comble cet écart. Les cas d'usage courants en Python incluent les en-têtes HTTP Basic Auth, les URI de données pour intégrer des images dans HTML ou CSS, les segments de tokens JWT, les pièces jointes MIME d'e-mails et le passage de blobs binaires via des variables d'environnement ou des API JSON.

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

base64.b64encode() — Guide d'encodage standard avec exemples

base64.b64encode(s, altchars=None)est la fonction d'encodage principale de la stdlib Python. Elle se trouve dans le module base64, fourni avec toutes les installations Python. La fonction accepte un objet bytes et retourne un objet bytes contenant la représentation ASCII Base64. Ce guide suppose Python 3.x (3.6+).

Exemple minimal fonctionnel

Python 3.6+
import base64

# Encodage d'une paire d'identifiants API pour un en-tête 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}")
# Valeur de l'en-tête : Basic ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==

Exemple étendu — sort_keys, objets imbriqués, décodage aller-retour

Python 3.6+
import base64
import json

# Encodage d'une configuration serveur structurée pour une variable d'environnement
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...

# Décoder et vérifier l'aller-retour
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
Remarque :b64decode() est permissif par défaut — il ignore silencieusement les caractères invalides, y compris les espaces blancs et les sauts de ligne. Passez validate=True pour lever une binascii.Errorsur tout caractère non Base64. Utilisez cela lors du décodage d'entrées non fiables provenant de systèmes externes.

Encodage de chaînes non ASCII et Unicode en Python

Les chaînes Python 3 sont Unicode par défaut. Le module base64 opère sur des bytes, pas sur des str— vous devez donc encoder la chaîne en bytes avant de la passer. Le choix de l'encodage est important : UTF-8 gère tous les points de code Unicode et est la valeur par défaut appropriée pour presque tous les cas d'usage.

Python 3.6+
import base64

# Encodage de contenu multilingue — noms d'utilisateurs d'une plateforme internationale
user_names = [
    "Thomas Dupont",        # Français — caractères ASCII standard
    "田中太郎",              # Idéogrammes CJK — 3 octets chacun en UTF-8
    "Мария Соколова",       # Cyrillique — U+041C et au-delà
    "Claire Martin",        # ASCII — 1 octet par caractère
]

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"Encodé    : {encoded}")
    print(f"Aller-ret.: {decoded}")
    print(f"Identique : {name == decoded}")
    print()

# Original  : Мария Соколова
# Encodé    : 0JzQsNGA0LjRjyDQodC+0LrQvtC70L7QstCw
# Aller-ret.: Мария Соколова
# Identique : True
Remarque :Si vous devez vérifier que l'encodage est correct pour une chaîne particulière, collez la sortie Base64 directement dans l'Encodeur Base64 de ToolDeck — il décode en temps réel et affiche la représentation exacte en octets UTF-8. Utile lors du débogage de cyrillique, CJK ou d'emojis dans des chaînes de charge utile.

Module base64 — Référence des fonctions

Le module base64expose plusieurs fonctions d'encodage. Voici la référence complète de celles que vous rencontrerez en pratique :

FonctionEntréeRetourneDescription
b64encode(s, altchars=None)bytesbytesBase64 standard (RFC 4648 §4). altchars remplace les caractères + et / par deux octets personnalisés.
b64decode(s, altchars=None, validate=False)bytes | strbytesDécode le Base64 standard. validate=True lève binascii.Error sur les caractères d'entrée invalides.
urlsafe_b64encode(s)bytesbytesBase64 URL-safe (RFC 4648 §5). Utilise - et _ à la place de + et /. Conserve le rembourrage =.
urlsafe_b64decode(s)bytes | strbytesDécode le Base64 URL-safe. Accepte une entrée avec ou sans rembourrage.
encodebytes(s)bytesbytesBase64 MIME : insère \n tous les 76 caractères et ajoute un \n final. Pour e-mail/MIME uniquement.
decodebytes(s)bytesbytesDécode le Base64 MIME. Ignore les espaces blancs et les sauts de ligne intégrés.
b16encode(s)bytesbytesEncodage hex (Base16). Chaque octet devient deux caractères hex majuscules. Sans rembourrage.
b32encode(s)bytesbytesEncodage Base32. Utilise A–Z et 2–7. Sortie plus grande que Base64 ; utilisé dans les secrets TOTP.

Le paramètre altchars dans b64encode accepte un objet de 2 octets qui substitue les caractères + et /. Passer altchars=b'-_' produit une sortie identique à urlsafe_b64encode mais vous permet de contrôler le rembourrage séparément.

Base64 URL-safe — urlsafe_b64encode() pour les JWT et paramètres de requête

Le Base64 standard utilise + et /, qui sont tous deux des caractères réservés dans les URL. Un + dans une chaîne de requête est décodé comme un espace, et / est un séparateur de chemin. Lorsque la valeur encodée apparaît dans une URL, un nom de fichier ou un cookie, vous avez besoin de la variante URL-safe : urlsafe_b64encode() substitue - à + et _ à /.

Les JWT utilisent le Base64 URL-safe sans rembourrage pour les trois segments (en-tête, charge utile, signature). Le rembourrage doit être supprimé manuellement — la stdlib Python le conserve.

Encodage d'un segment de charge utile JWT

Python 3.6+
import base64
import json

def encode_jwt_segment(data: dict) -> str:
    """Encode un dict en chaîne Base64 URL-safe sans rembourrage (format 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:
    """Décode un segment JWT Base64 URL-safe (gère le rembourrage manquant)."""
    # Remettre le rembourrage : Base64 exige une longueur multiple de 4
    padding  = 4 - len(segment) % 4
    padded   = segment + ("=" * (padding % 4))
    raw      = base64.urlsafe_b64decode(padded)
    return json.loads(raw)

# Construire un en-tête et une charge utile 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...

# Vérifier l'aller-retour
restored = decode_jwt_segment(payload_segment)
print(restored["role"])  # data-engineer
Remarque :urlsafe_b64decode() accepte les entrées avec ou sans rembourrage depuis Python 3.x, mais uniquement si les caractères sont URL-safe (- et _). Ne passez jamais une chaîne Base64 standard (avec + ou /) à urlsafe_b64decode — les caractères non concordants provoqueront une corruption silencieuse des données ou une binascii.Error.

Encodage de fichiers et de réponses API en Python

Dans le code de production, l'encodage Base64 apparaît le plus souvent autour de fichiers transmis et autour de réponses d'API externes qui livrent du contenu binaire. Ces deux scénarios nécessitent une gestion soigneuse de la frontière bytes.

Lecture d'un fichier depuis le disque et encodage

Python 3.6+
import base64
import json
from pathlib import Path

def encode_file_to_base64(file_path: str) -> str:
    """Lit un fichier binaire et retourne sa représentation encodée en Base64."""
    try:
        raw_bytes = Path(file_path).read_bytes()
        return base64.b64encode(raw_bytes).decode("ascii")
    except FileNotFoundError:
        raise FileNotFoundError(f"Fichier introuvable : {file_path}")
    except PermissionError:
        raise PermissionError(f"Permission refusée pour la lecture : {file_path}")

# Attacher un certificat TLS à un manifeste de déploiement
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",
    },
}

# Écrire le manifeste — le certificat est intégré en toute sécurité comme chaîne
with open("./dist/deployment-manifest.json", "w") as f:
    json.dump(deployment_manifest, f, indent=2)

print(f"Certificat encodé : {len(cert_b64)} caractères")

Encodage d'une réponse API HTTP pour le débogage

Python 3.6+
import base64
import requests  # pip install requests

def fetch_and_encode_binary(url: str, headers: dict | None = None) -> str:
    """Récupère une ressource binaire depuis une API et la retourne en Base64."""
    response = requests.get(url, headers=headers or {}, timeout=10)
    response.raise_for_status()  # lève HTTPError pour 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"Taille brute   : {len(response.content):,} octets")
    print(f"Taille encodée : {len(encoded):,} caractères")
    return encoded

# Exemple : télécharger une facture PDF signée depuis une API de facturation interne
invoice_b64 = fetch_and_encode_binary(
    "https://billing.internal/api/v2/invoices/INV-2026-0042/pdf",
    headers={"Authorization": "Bearer eyJhbGc..."},
)

# Attacher à une charge utile de notification
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"Charge utile prête : {len(str(notification)):,} caractères")

Comment encoder un fichier image en Base64 avec Python

Encoder une image en Base64 et l'intégrer comme URI de données est l'approche standard pour les templates d'e-mails HTML, la génération de PDF et les snapshots HTML autonomes. Le navigateur interprète directement la chaîne encodée — aucune requête d'image séparée n'est nécessaire. Le même modèle fonctionne pour tout type de fichier binaire : PNG, JPEG, SVG, WebP ou PDF.

Python 3.6+
import base64
import mimetypes
from pathlib import Path

def image_to_data_uri(image_path: str) -> str:
    """Convertit un fichier image en URI de données Base64 pour intégration inline en 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}"

# Intégrer des images produit inline dans un template d'e-mail HTML
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="Image principale du produit"
     width="768" height="432"
     style="display:block;max-width:100%" />
"""

print(f"L'URI de données PNG commence par : {hero_uri[:60]}...")
# data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAwAAAAA...
Remarque :Pour les fichiers SVG, une URI de données avec encodage URL (data:image/svg+xml,{encoded}) est souvent plus petite que Base64 car SVG est textuel et Base64 augmente la taille de ~33%. Utilisez Base64 pour les formats raster (PNG, JPEG, WebP) et l'encodage URL pour SVG.

Travail avec des fichiers volumineux — encodage Base64 par blocs

Charger un fichier entier en mémoire avec Path.read_bytes() convient pour les fichiers jusqu'à ~50 Mo. Au-delà de ce seuil, l'utilisation maximale de la mémoire devient significative — un fichier de 200 Mo nécessite ~200 Mo pour les octets bruts plus ~267 Mo pour la sortie Base64, soit ~467 Mo au total dans un seul processus. Pour les fichiers volumineux, lisez et encodez par blocs.

La contrainte critique : la taille du bloc doit être un multiple de 3 octets. Base64 encode 3 octets d'entrée en exactement 4 caractères de sortie. Si une limite de bloc tombe sur un non-multiple de 3, l'encodeur ajoute un rembourrage = en milieu de flux, rendant la sortie concaténée invalide.

Encodage en streaming vers un fichier (sans chargement complet en mémoire)

Python 3.6+
import base64
from pathlib import Path

CHUNK_SIZE = 3 * 1024 * 256  # 786 432 octets — multiple de 3, ~768 Ko par bloc

def encode_large_file(input_path: str, output_path: str) -> int:
    """
    Encode un fichier binaire volumineux en Base64 sans le charger entièrement en mémoire.
    Retourne le nombre de caractères Base64 écrits.
    """
    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

# Encoder une vidéo produit de 300 Mo pour un manifeste de livraison d'actifs
chars_written = encode_large_file(
    "./uploads/product-demo-4k.mp4",
    "./dist/product-demo-4k.b64",
)
print(f"Encodé : {chars_written:,} caractères Base64")
# Encodé : 407 374 184 caractères Base64

Encodage d'un répertoire d'actifs binaires (sortie NDJSON)

Python 3.6+
import base64
import json
from pathlib import Path

def encode_assets_to_ndjson(asset_dir: str, output_path: str) -> int:
    """
    Encode tous les fichiers binaires d'un répertoire dans un manifeste NDJSON.
    Chaque ligne est un objet JSON : {"path": "...", "mime": "...", "data": "<base64>"}
    Retourne le nombre de fichiers traités.
    """
    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} fichiers encodés dans le bundle d'actifs NDJSON")
Remarque :Passez de read_bytes()à la lecture par blocs quand le fichier d'entrée dépasse ~50–100 Mo, ou quand votre service traite de nombreux fichiers en parallèle et que la pression mémoire devient préoccupante. Pour les fichiers inférieurs à 50 Mo, le one-liner b64encode(path.read_bytes()).decode() est plus rapide et plus simple à comprendre.

Encodage Base64 en ligne de commande avec Python

Python fournit une interface CLI pour le module base64 — aucun outil supplémentaire nécessaire. Elle fonctionne sur toutes les plateformes, ce qui la rend utile dans les pipelines CI et les environnements Windows où la commande base64 système peut ne pas être disponible.

bash
# ── python -m base64 ───────────────────────────────────────────────────
# Encoder une chaîne (pipe stdin)
echo -n "deploy-svc:sk-prod-9f2a1c3e8b4d" | python3 -m base64
# ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==

# Encoder un fichier
python3 -m base64 ./ssl/service-client.crt

# Décoder une chaîne Base64
echo "ZGVwbG95LXN2Yzpzay1wcm9kLTlmMmExYzNlOGI0ZA==" | python3 -m base64 -d

# Décoder un fichier Base64 vers le binaire d'origine
python3 -m base64 -d ./dist/service-client.b64 > ./restored.crt

# ── Python one-liner — multiplateforme, fonctionne sur Windows ─────────
# Encoder une chaîne
python3 -c "import base64,sys; print(base64.b64encode(sys.argv[1].encode()).decode())" "my-secret"
# bXktc2VjcmV0

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

# Encoder un fichier inline (résultat sur stdout)
python3 -c "import base64,sys; print(base64.b64encode(open(sys.argv[1],'rb').read()).decode())" ./config.json
Remarque :Contrairement à la commande base64 système sous macOS, python -m base64ne coupe pas la sortie à 76 caractères par défaut. La sortie est une ligne continue, ce dont vous avez besoin pour les variables d'environnement, les champs JSON et les en-têtes HTTP. Utilisez-le comme remplacement du base64système sur n'importe quel OS.

Alternative haute performance : pybase64

Le module base64de la stdlib Python est implémenté en Python pur (avec une fine couche C dans CPython). Pour les services qui encodent de grandes charges utiles à haut débit — pipelines de traitement d'images, tâches d'export en masse, ingestion de télémétrie en temps réel — pybase64 est un remplacement direct soutenu par libbase64, une bibliothèque C accélérée par SIMD. Les benchmarks montrent des améliorations de performance de 2–10× selon la taille de la charge utile et l'architecture CPU.

bash
pip install pybase64
Python 3.6+
import pybase64
import time

# pybase64 est un remplacement direct — mêmes signatures de fonction que la stdlib
sample_payload = b"x" * (1024 * 1024)  # 1 Mo de données binaires

# Encodage standard — sortie identique à base64.b64encode()
encoded = pybase64.b64encode(sample_payload)
decoded = pybase64.b64decode(encoded)
assert decoded == sample_payload

# Encodage URL-safe — sortie identique à base64.urlsafe_b64encode()
url_safe = pybase64.urlsafe_b64encode(sample_payload)

# b64encode_as_string() retourne str directement — pas besoin d'appeler .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...

# Comparaison de performance (approximatif, varie selon le matériel)
# stdlib  base64.b64encode(1 Mo) :   ~80 Mo/s
# pybase64.b64encode(1 Mo) :         ~800 Mo/s (chemin SIMD sur CPU AVX2)

Passez à pybase64lorsque le profilage montre l'encodage Base64 comme un goulot d'étranglement, ou lorsque vous encodez des charges utiles supérieures à ~100 Ko de façon répétée. Pour l'encodage ponctuel de petites chaînes (identifiants, tokens), la stdlib est suffisamment rapide et n'a aucune dépendance d'installation.

Sortie terminal avec coloration syntaxique

Lors du débogage de charges utiles encodées en Base64 dans le terminal — notamment des configurations JSON ou des contenus JWT — la bibliothèque richvous offre une sortie avec coloration syntaxique et indentation bien plus lisible qu'un dump brut. Elle est particulièrement utile dans les outils CLI, les scripts de débogage et les sessions 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 = "Charge utile décodée") -> None:
    """Décode une chaîne Base64, l'analyse comme JSON et l'affiche avec coloration."""
    raw_bytes = base64.b64decode(encoded + "==")  # rembourrage tolérant
    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:
        # Pas du JSON — afficher le texte brut
        console.rule(f"[bold yellow]{label} (texte brut)")
        rprint(raw_bytes.decode("utf-8", errors="replace"))

# Inspecter un segment de charge utile JWT d'une requête d'authentification échouée
jwt_payload_segment = "eyJzdWIiOiJ1c3JfN2MzYTlmMWIyZCIsInJvbGUiOiJkYXRhLWVuZ2luZWVyIiwiZXhwIjoxNzQxOTEwNDAwfQ"
decode_and_pretty_print(jwt_payload_segment, "JWT Payload")
Remarque :Utilisez la sortie richuniquement pour l'affichage terminal — pour le débogage, la journalisation sur stdout ou les outils CLI interactifs. Ne l'utilisez jamais pour écrire une sortie Base64 dans des fichiers, la retourner depuis des endpoints API ou la stocker dans des variables d'environnement, car rich ajoute des codes d'échappement ANSI qui corrompent les données.

Erreurs courantes

J'ai examiné de nombreuses bases de code Python avec encodage Base64, et ces quatre erreurs apparaissent systématiquement — souvent non détectées jusqu'à ce qu'une entrée non ASCII ou un fichier binaire atteigne le chemin d'encodage en production.

Erreur 1 — Passer une str au lieu de bytes à b64encode()

Problème : b64encode() attend un objet bytes. Passer une str lève immédiatement un TypeError: a bytes-like object is required. Correction : appelez toujours .encode("utf-8") sur la chaîne avant d'encoder.

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)  # plante
import base64

# ✅ Encodez d'abord la str en bytes
webhook_secret = "wh-secret-a3f91c2b4d"
encoded = base64.b64encode(webhook_secret.encode("utf-8"))
# b'd2gtc2VjcmV0LWEzZjkxYzJiNGQ='

Erreur 2 — Oublier d'appeler .decode() sur le résultat bytes

Problème : b64encode() retourne des bytes, pas une str. L'intégrer directement dans une f-string produit b'...'dans la sortie, ce qui est une valeur d'en-tête HTTP invalide et casse la sérialisation JSON. Correction : appelez toujours .decode("ascii") sur le résultat encodé.

Before · Python
After · Python
import base64

credential = base64.b64encode(b"svc-monitor:sk-7f3a1b")
# ❌ L'en-tête Authorization contient "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}"}

Erreur 3 — Utiliser encodebytes() là où b64encode() est nécessaire

Problème : encodebytes() insère un \ntous les 76 caractères (retour à la ligne MIME) et ajoute un saut de ligne final. Stocker cela dans un champ JSON, une variable d'environnement ou une URI de données intègre des caractères de nouvelle ligne littéraux qui corrompent la valeur en aval. Correction : utilisez b64encode()partout sauf pour la composition d'e-mails MIME.

Before · Python
After · Python
import base64, json

cert_bytes = open("./ssl/root-ca.crt", "rb").read()
# ❌ encodebytes() ajoute \n tous les 76 chars — casse JSON et les variables d'env.
cert_b64 = base64.encodebytes(cert_bytes).decode()
config   = json.dumps({"ca_cert": cert_b64})  # sauts de ligne dans la valeur
import base64, json
from pathlib import Path

cert_bytes = Path("./ssl/root-ca.crt").read_bytes()
# ✅ b64encode() produit une chaîne continue sans interruption
cert_b64 = base64.b64encode(cert_bytes).decode("ascii")
config   = json.dumps({"ca_cert": cert_b64})  # valeur propre sur une seule ligne

Erreur 4 — Décoder du Base64 URL-safe avec le décodeur standard

Problème : Le Base64 URL-safe utilise - et _ à la place de + et /. Passer une chaîne URL-safe à b64decode()produit silencieusement des octets incorrects pour tout segment contenant ces caractères — aucune exception n'est levée par défaut. Correction : utilisez urlsafe_b64decode() pour les entrées URL-safe, ou passez validate=True pour détecter l'incompatibilité tôt.

Before · Python
After · Python
import base64

# ❌ Le segment JWT utilise Base64 URL-safe (- et _)
# b64decode() produit silencieusement des octets incorrects pour ces caractères
jwt_segment = "eyJzdWIiOiJ1c3JfN2MzYTlmMWIyZCIsInJvbGUiOiJhZG1pbiJ9"
wrong = base64.b64decode(jwt_segment)  # silencieusement incorrect si - ou _ présents
import base64

# ✅ Utilisez urlsafe_b64decode() pour les JWT et les entrées 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"}'

Méthodes Base64 Python — Comparaison rapide

MéthodeTypes d'entréeChars URL-safeRembourrageSauts de ligneRetourneNécessite install
b64encode()bytes, bytearray, memoryview❌ + et /✅ rembourrage =❌ aucunbytesNon
urlsafe_b64encode()bytes, bytearray, memoryview✅ - et _✅ rembourrage =❌ aucunbytesNon
b64encode(altchars=b"-_")bytes, bytearray, memoryview✅ 2 chars personnalisés✅ rembourrage =❌ aucunbytesNon
encodebytes()bytes, bytearray, memoryview❌ + et /✅ rembourrage =✅ \n toutes les 76 charsbytesNon
pybase64.b64encode()bytes, bytearray, memoryview❌ + et /✅ rembourrage =❌ aucunbytespip install
pybase64.b64encode_as_string()bytes, bytearray, memoryview❌ + et /✅ rembourrage =❌ aucunstrpip install

Choisissez b64encode()pour la grande majorité des cas d'usage : en-têtes HTTP, champs JSON, variables d'environnement et URI de données. Passez à urlsafe_b64encode() chaque fois que la sortie apparaîtra dans une URL, un nom de fichier, un cookie ou un segment JWT. Utilisez encodebytes()uniquement lors de la composition de pièces jointes d'e-mails MIME — le retour à la ligne est exigé par la spécification MIME mais cassera silencieusement tout le reste. Recourez à pybase64 lorsque vous encodez des charges utiles supérieures à ~100 Ko dans un chemin critique.

Questions fréquentes

Pourquoi base64.b64encode() retourne-t-il des bytes au lieu d'une chaîne ?
Python 3 sépare strictement le texte (str) et les données binaires (bytes). base64.b64encode() opère sur des données binaires et retourne des données binaires — même si les caractères de sortie sont de l'ASCII imprimable. Cette conception est intentionnelle : elle vous oblige à être explicite sur les frontières d'encodage. Pour obtenir une str, appelez .decode("ascii") ou .decode("utf-8") sur le résultat. Comme la sortie Base64 valide ne contient que des caractères ASCII, les deux encodages produisent des résultats identiques.
Quelle est la différence entre b64encode() et encodebytes() en Python ?
b64encode() produit une seule chaîne Base64 continue — le bon choix pour les en-têtes HTTP, les champs JSON, les URI de données, les variables d'environnement et les segments JWT. encodebytes() (anciennement encodestring() en Python 2) insère un caractère de nouvelle ligne tous les 76 octets et ajoute un saut de ligne final. C'est le format de retour à la ligne MIME requis pour les pièces jointes d'e-mail selon le RFC 2045. Utiliser encodebytes() en dehors de la composition d'e-mails intégrera des sauts de ligne littéraux dans votre sortie, corrompant les en-têtes, les chaînes JSON et les valeurs d'URL.
Comment encoder en Base64 une chaîne avec des caractères non ASCII en Python ?
Appelez .encode("utf-8") sur la chaîne pour la convertir en bytes, puis passez ces bytes à base64.b64encode(). Pour décoder, inversez les étapes : base64.b64decode(encoded), puis .decode("utf-8") sur le résultat. UTF-8 est le bon choix pour presque tout le texte — il gère tous les points de code Unicode, y compris le cyrillique, les idéogrammes CJK, l'arabe et les emojis. Utiliser .encode("ascii") sur du texte non ASCII lèvera un UnicodeEncodeError, ce qui est généralement le comportement correct car cela expose l'incompatibilité d'encodage tôt.
Comment encoder en Base64 un fichier en Python ?
Lisez le fichier en mode binaire, puis appelez base64.b64encode() sur les bytes. Le one-liner le plus simple est : encoded = base64.b64encode(Path("file.bin").read_bytes()).decode("ascii"). Pour les fichiers volumineux (au-delà de ~50–100 Mo), évitez de charger le fichier entier en mémoire. Lisez plutôt par blocs d'une taille multiple de 3 octets (ex. : 3 × 1024 × 256 = 786 432 octets) et encodez chaque bloc séparément — les tailles de blocs multiples de 3 évitent que des caractères de rembourrage = n'apparaissent en milieu de sortie.
Pourquoi urlsafe_b64encode() de Python inclut-il encore le rembourrage = ? JWT ne l'utilise pas.
La stdlib suit la spécification RFC 4648 §5, qui conserve le rembourrage =. JWT (RFC 7519) définit son propre encodage Base64url qui supprime entièrement le rembourrage. L'incompatibilité est une décision délibérée de la spécification : le rembourrage RFC 4648 rend la chaîne autodescriptive (vous pouvez toujours déterminer la longueur en octets d'origine), tandis que JWT le supprime pour réduire la longueur du token. Pour correspondre au format JWT, appelez .rstrip(b"=") sur la sortie encodée avant de décoder avec .decode("ascii"). Lors du décodage, rajoutez le rembourrage correct : padding = 4 - len(segment) % 4; padded = segment + "=" * (padding % 4).
Existe-t-il un moyen de valider qu'une chaîne est du Base64 valide avant de la décoder ?
Passez validate=True à base64.b64decode(). Avec cet indicateur, tout caractère en dehors de l'alphabet Base64 standard (A–Z, a–z, 0–9, +, /, =) lève une binascii.Error. Sans validate=True, b64decode() ignore silencieusement les caractères invalides, ce qui peut masquer des entrées corrompues. Pour le Base64 URL-safe, il n'y a pas de paramètre validate dans urlsafe_b64decode() — vous pouvez valider manuellement avec une regex : import re; bool(re.fullmatch(r"[A-Za-z0-9_-]+=*", segment)). Validez toujours les entrées de sources externes non fiables avant de décoder.

Outils associés

Pour encoder ou décoder en un clic sans écrire de Python, collez votre chaîne ou fichier directement dans l' Encodeur Base64 — il gère les modes standard et URL-safe instantanément dans votre navigateur, sans configuration requise.

Aussi disponible en :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 SharmaRéviseur technique

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.