Tokenizers
Provides an implementation of today's most used tokenizers, with a focus on performance and versatility.
Bindings over the Rust implementation. If you are interested in the High-level design, you can go check it there.
Otherwise, let's dive in!
Main features:
- Train new vocabularies and tokenize using 4 pre-made tokenizers (Bert WordPiece and the 3 most common BPE versions).
- Extremely fast (both training and tokenization), thanks to the Rust implementation. Takes less than 20 seconds to tokenize a GB of text on a server's CPU.
- Easy to use, but also extremely versatile.
- Designed for research and production.
- Normalization comes with alignments tracking. It's always possible to get the part of the original sentence that corresponds to a given token.
- Does all the pre-processing: Truncate, Pad, add the special tokens your model needs.
Installation
With pip:
pip install tokenizers
From sources:
To use this method, you need to have the Rust installed:
# Install with:
curl https://sh.rustup.rs -sSf | sh -s -- -y
export PATH="$HOME/.cargo/bin:$PATH"
Once Rust is installed, you can compile doing the following
git clone https://github.com/huggingface/tokenizers
cd tokenizers/bindings/python
# Create a virtual env (you can use yours as well)
python -m venv .env
source .env/bin/activate
# Install `tokenizers` in the current virtual env
pip install -e .
Free-threaded Python (3.14t)
tokenizers ships dedicated wheels for the free-threaded build of CPython
(python3.14t). These wheels declare Py_MOD_GIL_NOT_USED, so importing
tokenizers does not force the GIL back on — multi-threaded code stays
GIL-free.
The full mutable API works on 3.14t — the same as on regular CPython.
Setters are thread-safe: the inner tokenizer state is wrapped in a
std::sync::RwLock, so concurrent tokenizer.X = … from multiple threads
serialize correctly and concurrent encode operations take a read guard
that blocks writers only briefly.
from tokenizers import Tokenizer
from tokenizers.models import BPE
from tokenizers.pre_tokenizers import Whitespace
from tokenizers.processors import ByteLevel
tok = Tokenizer(BPE())
tok.pre_tokenizer = Whitespace() # ✅ thread-safe on 3.14t
tok.post_processor = ByteLevel(trim_offsets=True)
Caveat — compound mutations are not atomic. Statements like
tokenizer.post_processor.special_tokens = X evaluate in two steps from
Python's point of view (read attribute → set attribute on the result). If
another thread swaps tokenizer.post_processor between those steps, the
mutation lands on an orphaned component. This is the same class of race
as dict[k] = v interleaved with dict.clear() — coordinate with a Python
lock if you need the compound to be atomic.
For the full thread-safety analysis, see
docs/free-threading-audit.md.
Load a pretrained tokenizer from the Hub
from tokenizers import Tokenizer
tokenizer = Tokenizer.from_pretrained("bert-base-cased")
Using the provided Tokenizers
We provide some pre-build tokenizers to cover the most common cases. You can easily load one of
these using some vocab.json and merges.txt files:
from tokenizers import CharBPETokenizer
# Initialize a tokenizer
vocab = "./path/to/vocab.json"
merges = "./path/to/merges.txt"
tokenizer = CharBPETokenizer(vocab, merges)
# And then encode:
encoded = tokenizer.encode("I can feel the magic, can you?")
print(encoded.ids)
print(encoded.tokens)
And you can train them just as simply:
from tokenizers import CharBPETokenizer
# Initialize a tokenizer
tokenizer = CharBPETokenizer()
# Then train it!
tokenizer.train([ "./path/to/files/1.txt", "./path/to/files/2.txt" ])
# Now, let's use it:
encoded = tokenizer.encode("I can feel the magic, can you?")
# And finally save it somewhere
tokenizer.save("./path/to/directory/my-bpe.tokenizer.json")
Provided Tokenizers
CharBPETokenizer: The original BPEByteLevelBPETokenizer: The byte level version of the BPESentencePieceBPETokenizer: A BPE implementation compatible with the one used by SentencePieceBertWordPieceTokenizer: The famous Bert tokenizer, using WordPiece
All of these can be used and trained as explained above!
Build your own
Whenever these provided tokenizers don't give you enough freedom, you can build your own tokenizer, by putting all the different parts you need together. You can check how we implemented the provided tokenizers and adapt them easily to your own needs.
Building a byte-level BPE
Here is an example showing how to build your own byte-level BPE by putting all the different pieces together, and then saving it to a single file:
from tokenizers import Tokenizer, models, pre_tokenizers, decoders, trainers, processors
# Initialize a tokenizer
tokenizer = Tokenizer(models.BPE())
# Customize pre-tokenization and decoding
tokenizer.pre_tokenizer = pre_tokenizers.ByteLevel(add_prefix_space=True)
tokenizer.decoder = decoders.ByteLevel()
tokenizer.post_processor = processors.ByteLevel(trim_offsets=True)
# And then train
trainer = trainers.BpeTrainer(
vocab_size=20000,
min_frequency=2,
initial_alphabet=pre_tokenizers.ByteLevel.alphabet()
)
tokenizer.train([
"./path/to/dataset/1.txt",
"./path/to/dataset/2.txt",
"./path/to/dataset/3.txt"
], trainer=trainer)
# And Save it
tokenizer.save("byte-level-bpe.tokenizer.json", pretty=True)
Now, when you want to use this tokenizer, this is as simple as:
from tokenizers import Tokenizer
tokenizer = Tokenizer.from_file("byte-level-bpe.tokenizer.json")
encoded = tokenizer.encode("I can feel the magic, can you?")
Typing support and stub generation
The compiled PyO3 extension does not expose type annotations, so editors and type checkers would otherwise see most objects as Any. To provide full typing support, we use a two-step stub generation process:
- Rust introspection (
tools/stub-gen/): Usespyo3-introspectionto analyze the compiled extension and generate.pyistub files - Python enrichment (
stub.py): Adds docstrings from the runtime module and generates forwarding__init__.pyshims
Running stub generation
The easiest way to regenerate stubs is via make style:
cd bindings/python
make style
This will:
- Build the extension with
maturin develop --release - Run introspection to generate
.pyifiles - Enrich stubs with docstrings via
stub.py - Format with
ruff
Running manually
To run the stub generator directly:
cd bindings/python
cargo run --manifest-path tools/stub-gen/Cargo.toml
python stub.py
The stub generator automatically:
- Builds the extension using maturin
- Copies the built
.soto the project root for introspection - Detects and sets
PYTHONHOMEfor embedded Python (handles uv/venv environments) - Generates stubs to
py_src/tokenizers/
Troubleshooting
If you encounter Python initialization errors, you can manually set PYTHONHOME:
export PYTHONHOME=$(python3 -c 'import sys; print(sys.base_prefix)')
cargo run --manifest-path tools/stub-gen/Cargo.toml
3 maintainers
Release files for tokenizers 0.23.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tokenizers-0.23.2.tar.gz | 385.7 kB | Details |
Built distributions (wheels)
Total release size: 80.3 MB
Release files / tokenizers-0.23.2.tar.gz
| Download URL | tokenizers-0.23.2.tar.gz |
|---|---|
| Size | 385.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f0f085686b9de0d0079e6f874ae053600db64c5d13049e0bbc0119926d25aac
|
|
BLAKE2b-256 checksum How to use checksums |
181ebc6587c5ab643b2e17776cace9070a2ae73549c86bffac9934a600bf3c31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-win_arm64.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-win_arm64.whl |
|---|---|
| Size | 2.7 MB |
| Tags | CPython 3.10 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
e49c394456dd9985787fec76132438ba3fb8911f857b1bf3d40119f9292d41aa
|
|
BLAKE2b-256 checksum How to use checksums |
d7b0dee84cb44175be1b4c35bd2f770727494e78f0bb38e571a623ade94dbebb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-win_amd64.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
2e96f5699d5249c9c64aa8412e044f727aae3a4098cf830f9901ec1afc361cde
|
|
BLAKE2b-256 checksum How to use checksums |
dbf70a69ac6b82dbccf3f71add938a161c497952749294b8dd6dfe03a819dc40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-win32.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-win32.whl |
|---|---|
| Size | 2.6 MB |
| Tags | CPython 3.10 Windows x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
debf978920d93ba9c219bd67cc4bbfaf912c9039e41e7a28b91ec15e3728c95a
|
|
BLAKE2b-256 checksum How to use checksums |
f31fc79a01f671a49728ebb0b61f7ff9ea45663b66cab40bc0858e9859b25c16
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 10.3 MB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
5c56bda1511921587789163e524d196ed8284174ac23abd7685d5ea8da6c4718
|
|
BLAKE2b-256 checksum How to use checksums |
b5d88e9e4e0b287a338d8f88976729628c9d22e8a54cfaf9777018a7f7cb58a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-musllinux_1_2_i686.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-musllinux_1_2_i686.whl |
|---|---|
| Size | 10.1 MB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
bef235815a067b2648caf6dcc7a71091b0b0fff9ee8057f6451eb9335fae52ef
|
|
BLAKE2b-256 checksum How to use checksums |
fa737038e612d48bda1599457f712f6bd3854eae1a9dc9c13aa47f835349db48
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-musllinux_1_2_armv7l.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-musllinux_1_2_armv7l.whl |
|---|---|
| Size | 9.8 MB |
| Tags | CPython 3.10 Linux musl 1.2+ ARMv7l abi3 |
|
SHA-256 checksum How to use checksums |
f486f402f6f9abee5bb032553736813af0c710a86b2e0ca592634c55cea1f835
|
|
BLAKE2b-256 checksum How to use checksums |
06013ccb3a956c7528b2507b8a9714155c4baf86af593039db6ea375dd0c96c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 10.0 MB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
eb2f9c8a24da020ea8c11a01a19c1c2547912d92121ae4a01cfbca46125dee40
|
|
BLAKE2b-256 checksum How to use checksums |
8d6a1552b70fb0d9ab074fd3fc961435d01364e79c9058481822c3af6e8d402c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-manylinux_2_31_riscv64.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-manylinux_2_31_riscv64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.10 Linux glibc 2.31+ RISC-V 64 abi3 |
|
SHA-256 checksum How to use checksums |
12f0835dc2ee694746a76adf7b1567d4346a4a502ebe93fb1f5f80ea49799b78
|
|
BLAKE2b-256 checksum How to use checksums |
e9a44f9106d317b14a80aefea9f0e3a8d07ef25f856a7607eb7f5ab894281fcb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
41c2f84d172449b4dadb9cdc508e3e364076613c35b16e76ecfe47a60d1e3305
|
|
BLAKE2b-256 checksum How to use checksums |
2ccaca6b93c7820df123b2662a9469e8facc826ccc94e98fdd0d615f6431e73a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ IBM System/390x abi3 |
|
SHA-256 checksum How to use checksums |
950d7c9426fa72406a0ffeacdbc0bb9985f5db20eb8b263f29c79aaf83105703
|
|
BLAKE2b-256 checksum How to use checksums |
9b8a0175e216f005c2fe08238292663aa41e4c802b216e71047a69a0e9fc6fa3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl |
|---|---|
| Size | 4.0 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ PowerPC 64-le abi3 |
|
SHA-256 checksum How to use checksums |
325fee2e0418a9dc6c9ecf736a5f5f0db7875183ace9549ae339da76f7a1fbb7
|
|
BLAKE2b-256 checksum How to use checksums |
2db756b84b80bc96942bba8eb23751a9e8a1fce4faaf4390425e7083f721c98c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
43e4f2071e3cc8d5d86421c874aebc82659bb51a68bcdef5a0da75ee89511ccb
|
|
BLAKE2b-256 checksum How to use checksums |
c5bd93c69152d02ef06ce47aed8b2bf4952dcf733c935a62791873932b2934d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARMv7l abi3 |
|
SHA-256 checksum How to use checksums |
7b7e37ba198f24150f523e1242e83c4970de4a525480586be5dcc24d9add32c5
|
|
BLAKE2b-256 checksum How to use checksums |
2adee2f14c8919d5bf51874051d00d6c7b7e0e8bde6c6a2dbeddda7f642896ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
a37039b5dfc4af84eb3ef0a92f4307e28936c8f9adccba2629d36f652e9bf7a2
|
|
BLAKE2b-256 checksum How to use checksums |
2e4d8f569ed49372a3ed8e57099bd515055fd48d7c95912c4307cda6973c2168
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
986670e43691469dcee610ea0f846f91a8f84e91fc6f7a48d4c064414c0ec2bf
|
|
BLAKE2b-256 checksum How to use checksums |
674922da045a91732384d3a3771816bf188dc5a1f702c32e635afa7c679c0bef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / tokenizers-0.23.2-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | tokenizers-0.23.2-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
85a9a357a3764aecc904ee76bdaf8cf1ad8e5a67a1b929a487c4a39b49ed0e90
|
|
BLAKE2b-256 checksum How to use checksums |
4ded8a443528baa6fac8dfe8c3b75b038c63ac92bb539bcabe311e227c718173
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
