Base64 vs Base64URL: Differences, Padding and Code

Side-by-side reference

RFC 4648 is explicit that the URL-safe variant “should not be regarded as the same as the ‘base64’ encoding and should not be referred to as only ‘base64’.” If an API says “base64” and rejects your input, the alphabet is the first thing to check.

Node.js: Buffer supports both encodings natively

The bytes FB FF BF are a handy test input because their Base64 form is exactly +/+/. The Node docs state that 'base64url'“will omit padding” when encoding, and that both decoders accept the other alphabet:

const bytes = Buffer.from([0xfb, 0xff, 0xbf]);
console.log(bytes.toString('base64'));      // +/+/
console.log(bytes.toString('base64url'));   // -_-_

const s = Buffer.from('hi');
console.log(s.toString('base64'), '|', s.toString('base64url'));   // aGk= | aGk

// Decoding is lenient in both directions
console.log(Buffer.from('-_-_', 'base64').toString('hex'));     // fbffbf
console.log(Buffer.from('+/+/', 'base64url').toString('hex'));  // fbffbf
console.log(Buffer.from('aGk', 'base64url').toString());        // hi  (unpadded is fine)

Because Node is lenient, code that “works” there can fail on stricter decoders elsewhere. Always emit the variant the consumer documents.

Browser: btoa/atob only speak standard Base64

btoa() produces the standard alphabet with padding, and atob() expects it. Convert with two replacements and a padding step ((4 - len % 4) % 4 equals signs):

const toBase64Url = (b64) =>
  b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

const fromBase64Url = (u) => {
  const b = u.replace(/-/g, '+').replace(/_/g, '/');
  return b + '='.repeat((4 - (b.length % 4)) % 4);
};

const std = Buffer.from([0xfb, 0xff, 0xbf, 0xff]).toString('base64');
console.log(std);                        // +/+//w==
console.log(toBase64Url(std));           // -_-__w
console.log(fromBase64Url('-_-__w'));    // +/+//w==
console.log(atob(fromBase64Url('aGk'))); // hi

btoa() also throws on characters above U+00FF; encode text with TextEncoder first, as explained in What Is Base64 Encoding?.

Python: urlsafe_b64encode keeps the padding

The Python documentation for base64.urlsafe_b64encode says the result “can still contain =”, and urlsafe_b64decode raises on missing padding. Strip on the way out, restore on the way in:

import base64

raw = bytes([0xFB, 0xFF, 0xBF])
print(base64.b64encode(raw))            # b'+/+/'
print(base64.urlsafe_b64encode(raw))    # b'-_-_'
print(base64.urlsafe_b64encode(b"hi"))  # b'aGk='   <- padding is kept

def b64url_encode(b: bytes) -> str:
    return base64.urlsafe_b64encode(b).rstrip(b"=").decode()

def b64url_decode(s: str) -> bytes:
    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))

print(b64url_encode(b"hi"), b64url_decode("aGk"))   # aGk b'hi'

base64.urlsafe_b64decode("aGk")
# binascii.Error: Incorrect padding

One more Python trap: b64decode(s) with the default validate=False silently discards characters outside its alphabet. Feeding it a Base64URL string does not convert - and _, it deletes them and returns wrong bytes. Use urlsafe_b64decode, or pass altchars=b"-_", or set validate=True to fail loudly.

Frequently Asked Questions

Related guides

• What Is Base64 Encoding? How It Works & When to Use It
• Base64 Encoding Explained: Uses, Padding, Base64url & Security