---
title: "Base32"
description: "Base32 in four alphabets. RFC 4648 with A to Z and 2 to 7 or its hex alphabet plus Crockford's and z-base-32 for people"
canonical_url: "https://encodings.agntn.dev/encodings/base32"
---
# Base32

> Base32 in four alphabets. RFC 4648 with A to Z and 2 to 7 or its hex alphabet plus Crockford's and z-base-32 for people

<encoding-facts name="base32">



</encoding-facts>

Letters and the digits 2 to 7. It survives a file system that ignores case. It survives a person who confuses `0` with `O`, too. The secret behind your authenticator app? Base32. Onion v3 addresses as well.

```ts
encode("base32", "foobar");  // "MZXW6YTBOI======"
```

That's the RFC 4648 test vector. Five bytes become eight characters, and the last block pads with `=`. Decoding takes lowercase and the text with or without padding. Wrong padding is an error, though. Six `=` where the length needs four means something got mangled on the way.

And who pads anyway? Stellar addresses don't. TOTP secrets don't either. Pass `padding: false` and you don't have to:

```ts
encode("base32", "foobar", { padding: false });  // "MZXW6YTBOI"
```

Five bits a character leaves room for taste. Four alphabets made it into real use, and `alphabet` picks one. Decoding takes it too.

## Why do `MY` and `MZ` decode the same?

One byte is eight bits. Two base32 characters are ten. The two spare bits go out as zero, and decoding doesn't look at them. So `MY======` is `f`, and `MZ======` is `f` too.

Text copied by hand doesn't care. A key or an address might. A stray bit there is a bug waiting for its turn, and `canonical: true` wants those bits zero:

```ts
decode("base32", "MZ======", { canonical: true });
// DecodeError: "Z" (U+005A) at index 1 leaves non-zero bits after the last byte
```

Only the spare bits, mind. Lowercase, spaces and a missing `=` still read fine. Every alphabet takes it, and only `decode` does, since `encode` writes zeros anyway.

## The hex alphabet

The same RFC has a second alphabet, `0` to `9` and `A` to `V`. Why bother? Order. Sort the encoded strings and they line up exactly like the bytes. Plain base32 can't do that.

```ts
encode("base32", "foobar", { alphabet: "hex" });           // "CPNMUOJ1E8======"
decode("base32", "CPNMUOG=", { alphabet: "hex" }).bytes;  // "foob"
```

Decoding needs the alphabet too. `CPNMUOG=` fits both, and without it that's four other bytes. No error, just wrong. DNSSEC writes NSEC3 owner names in this alphabet, unpadded, so DNS wants `padding: false` as well.

## The crockford alphabet

Douglas Crockford's take. No `I`, `L`, `O` or `U`. Nothing reads as something else. And nothing spells a rude word by accident, which is why `U` had to go. ULIDs use this alphabet.

```ts
encode("base32", "foobar", { alphabet: "crockford" });  // "CSQPYRK1E8"
decode("base32", "csqp-yrki-e8", { alphabet: "crockford" });
// the same six bytes: lowercase, hyphens, and i read as 1
```

Decoding ignores case and hyphens. It reads `O` as `0` and `I` or `L` as `1`. Lenient? No, that's the spec. It never pads, so `padding` does nothing here. This is the byte encoding. Crockford also defines a number encoding with a check symbol, which isn't here.

## The z alphabet

z-base-32. Zooko O'Whielacronx reordered the alphabet in 2002, so the characters that show up most are the easiest to read, write and say. Lowercase only, no padding. Ever read a key out loud over a call? That's who this is for.

```ts
base32.encode(new Uint8Array([0xf0, 0xbf, 0xc7]), { alphabet: "z" });  // "6n9hq"
encode("base32", "hello", { alphabet: "z" });                          // "pb1sa5dx"
```

`6n9hq` is the example from the original paper. Zooko wrote it for Mnet. These days you meet it in Lightning, where node message signatures come out as z-base-32.


## Sitemap

See the full [sitemap](https://encodings.agntn.dev/sitemap.md) for all pages.
