base64 — RFC 4648 encodings

base64.b64encode and b64decode, URL-safe alphabets, padding errors, and validate=True. Base64 is an encoding, not encryption.

The base64 module implements RFC 4648 encodings. It maps bytes to ASCII text and back. That is an encoding, not encryption: anyone can decode the result, and it does not provide confidentiality, integrity, or authentication.

b64encode and b64decode use the standard alphabet with + and /. urlsafe_b64encode and urlsafe_b64decode use - and _ instead, which is the alphabet intended for use in URLs and filenames. The functions accept bytes and, for decode, also ASCII strings. They return bytes. If you need a str, decode those bytes as ASCII as a separate step.

Examples were checked against Python 3.13. See the official documentation for the complete API.

Python reference overview →

b64encode and URL-safe alphabets

b64encode(b"hi?") is b"aGk/". The same bytes with a + or / in the alphabet become - or _ under the URL-safe functions: b64encode(b"\xfb\xff") is b"+/8=", and urlsafe_b64encode of the same input is b"-_8=". Decode with the matching function. Padding with = is part of the encoded form; shorter inputs use one or two padding characters (YQ==, YWI=, YWJj).

base64.b64encode, base64.b64decode, base64.urlsafe_b64encode, base64.urlsafe_b64decode

base64.b64encode(s, altchars=None)
base64.b64decode(s, altchars=None, validate=False)
base64.urlsafe_b64encode(s)
base64.urlsafe_b64decode(s)

Encode and decode bytes with the standard or URL-safe Base64 alphabet. The result of encode is still just encoded bytes, not a secret.

ParameterDescription
sFor encode, a bytes-like object. For decode, a bytes-like object or an ASCII string of encoded data.
altcharsAn optional two-character replacement for + and / in the standard functions.

Returns: All four functions return bytes. encode returns the encoded form, including padding when required; decode returns the original bytes.

  • These outputs were measured on Python 3.13.12.
python
import base64

print(base64.b64encode(b"hi?"))
print(base64.b64decode(b"aGk/"))
print(base64.b64encode(b"\xfb\xff"), base64.urlsafe_b64encode(b"\xfb\xff"))
print(base64.b64encode(b"a"), base64.b64encode(b"ab"), base64.b64encode(b"abc"))

Expected output

b'aGk/'
b'hi?'
b'+/8=' b'-_8='
b'YQ==' b'YWI=' b'YWJj'

Official documentation →

Padding and validate

Official documentation says b64decode raises binascii.Error if the input is incorrectly padded. The string YQ, without ==, is such a case. If validate is False (the default), characters that are not in the alphabet are discarded before the padding check, so YQ==!!! still decodes as b"a". If validate is True, those extra characters raise binascii.Error: Excess data after padding. Use validate=True when the input must be strict Base64.

base64.b64decode

base64.b64decode(s, altchars=None, validate=False)

Reject missing padding always, and reject non-alphabet characters when validate is True. The default decoder is not a strict validator.

ParameterDescription
sThe encoded input, as bytes or an ASCII string.
validateIf True, non-alphabet characters cause binascii.Error. If False, they are discarded before the padding check.

Returns: The decoded bytes when the input is accepted.

Raises

  • binascii.Error — Raised for incorrect padding, and for extra or illegal characters when validate is True. The measured messages on Python 3.13.12 are "Incorrect padding" and "Excess data after padding".
  • The printed type name is binascii.Error. Do not treat a successful default decode of messy input as proof that the string was well formed.
python
import base64

print(base64.b64decode(b"YQ=="))
try:
    base64.b64decode(b"YQ")
except Exception as err:
    print(f"{err.__class__.__module__}.{type(err).__name__}: {err}")
print(base64.b64decode(b"YQ==!!!"))
try:
    base64.b64decode(b"YQ==!!!", validate=True)
except Exception as err:
    print(f"{err.__class__.__module__}.{type(err).__name__}: {err}")

Expected output

b'a'
binascii.Error: Incorrect padding
b'a'
binascii.Error: Excess data after padding

Official documentation →