Install & Compatibility
Where this runs
tested against v0.9.12 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.026s · 25.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.026s · 23MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Trainer
✓ from pycrfsuite import Trainer
✗ import pycrfsuite
trainer = pycrfsuite.Trainer(...)
Tagger
✓ from pycrfsuite import Tagger
✗ import pycrfsuite
tagger = pycrfsuite.Tagger(...)
ItemSequence
✓ from pycrfsuite import ItemSequence
✗ import pycrfsuite
item_sequence = pycrfsuite.ItemSequence(...)
This quickstart demonstrates how to train a Conditional Random Field (CRF) model using `pycrfsuite.Trainer` and then use the trained model with `pycrfsuite.Tagger` to predict labels for new sequences. The example uses a simple list-of-lists format for features and labels, which is common for sequence labeling tasks.
import pycrfsuite
import os
# Sample data (features, labels)
X_train = [
[['walk', 'big'], ['dog']],
[['eat', 'apple'], ['red', 'apple']],
[['run', 'fast'], ['cat']]
]
y_train = [
['VERB', 'NOUN'],
['VERB', 'NOUN'],
['VERB', 'NOUN']
]
# 1. Train a CRF model
trainer = pycrfsuite.Trainer(verbose=False)
for xseq, yseq in zip(X_train, y_train):
trainer.append(xseq, yseq)
trainer.set_params({
'c1': 1.0, # coefficient for L1 penalty
'c2': 1e-3, # coefficient for L2 penalty
'max_iterations': 50, # stop earlier
'feature.possible_transitions': True
})
model_filename = 'model.crfsuite'
trainer.train(model_filename)
print(f"Model trained and saved to '{model_filename}'")
# 2. Use the trained model for tagging
tagger = pycrfsuite.Tagger()
tagger.open(model_filename)
X_test = [
[['see', 'small'], ['dog']]
]
predicted_tags = [tagger.tag(xseq) for xseq in X_test]
print(f"Test sequence: {X_test}")
print(f"Predicted tags: {predicted_tags}")
# Clean up the model file
os.remove(model_filename)
Debug
Known issues
breakingVersion 0.9.12 dropped support for Python 3.6, 3.7, 3.8, and 3.9. Users on these older Python versions must either upgrade their Python environment or pin to an older `python-crfsuite` version.fixUpgrade your Python environment to 3.10 or newer (3.10, 3.11, 3.12, 3.13, 3.14 are supported). If unable to upgrade, pin to `python-crfsuite<0.9.12`.
affects: 0.9.12 and later
gotchaThe PyPI package name is `python-crfsuite`, but the module to import in your Python code is `pycrfsuite`.fixAlways use `import pycrfsuite` in your Python code, even though you install it with `pip install python-crfsuite`.
affects: All versions
gotchaThe input data format for `Trainer.append()` and `Tagger.tag()` requires a list of feature lists for each item in the sequence. Each feature list is typically a list of strings (e.g., `[['feature1', 'feature2'], ['feature3']]`). Incorrectly formatted input will lead to errors.fixEnsure your feature sequences are formatted as `list[list[str]]` where the outer list represents the sequence, and each inner list represents the features for a single token/item in that sequence. Refer to the quickstart for an example.
affects: All versions
Upgrade
Version history
0.9.12latest on PyPI · released Dec 23, 2025
Audit
Dependencies
No dependency data recorded yet.