Base64 variants: standard vs URL-safe alphabets, padding rules and decoder strictness

What it is

Variant	Alphabet chars 62/63	Padding	Line wrapping
Standard base64 (RFC 4648 §4)	+ /	required unless the referring spec overrides it — "MUST include appropriate pad characters"	forbidden unless the referring spec asks for it
URL-safe / base64url (RFC 4648 §5)	- _	same rule as standard, unless overridden; the RFC notes padding can be skipped when the length is known	forbidden unless the referring spec asks for it
JWT / JWS BASE64URL (RFC 7515)	- _	explicitly omitted — "with all trailing '=' characters omitted"	none allowed — "without the inclusion of any line breaks"
MIME (RFC 2045)	+ /	required	required — no more than 76 characters per line; decoders must ignore characters outside the alphabet

Why it matters

RFC 4648 defines two alphabets differing in exactly two characters, and states padding is required "unless the specification referring to this document explicitly states otherwise." JWTs are exactly such an override: RFC 7515 omits trailing = characters entirely and forbids line breaks, so a JWT segment padded with = or wrapped across lines is invalid input to a strict decoder. MIME requires the opposite: lines of no more than 76 characters, and GNU's base64 command wraps output at that width by default, so it needs an explicit -w0 to produce a single unbroken line (-w is a GNU coreutils option; macOS's base64 does not wrap by default and uses -b to request line breaks). Decoders then disagree on how forgiving to be: Python's base64.b64decode discards characters outside the alphabet before checking padding unless validate=True is passed — so a base64url string fed to it loses its - and _ and either decodes to wrong bytes or fails on padding, never naming the bad characters — and it raises Incorrect padding on unpadded input, which is exactly what base64.urlsafe_b64decode does with a JWT segment. A browser's atob() throws an InvalidCharacterError on -, _ or any other character outside the standard alphabet, yet accepts missing padding and ignores ASCII whitespace. Go's encoding/base64 keeps StdEncoding and URLEncoding as separate, non-interchangeable codecs, with RawStdEncoding/RawURLEncoding as the explicit padding-less forms.

How to apply

• Match the alphabet to the context: URL/filename/JWT contexts need -/_; everything else defaults to +//.
• Strip or add padding deliberately: JWTs must have none; most other consumers expect it unless documented otherwise.
• Use base64 -w0 whenever scripted output must be a single line.
• Do not rely on base64.b64decode's default leniency; pass validate=True when malformed input should be rejected outright.
• Before decoding an unpadded base64url value in Python, append '=' * (-len(s) % 4); in Go, use RawURLEncoding.

Pitfalls

• Feeding a padded, +//-alphabet string to a decoder expecting base64url.
• Assuming every decoder discards stray characters the way Python's default does — atob() throws instead.
• Assuming -w0 is portable: it is a GNU coreutils option, and macOS's base64 uses -b instead.
• Forgetting -w0 is needed to avoid line breaks in scripted base64 output.