Install & Compatibility
Where this runs
tested against v0.2.26 · 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
py 3.10
✕ dependency_conflict
✓ 87.78s
py 3.11
✕ dependency_conflict
✓ 83.2s
py 3.12
✕ dependency_conflict
✓ 75.9s
py 3.13
✕ no_wheel
7/8 runs
py 3.9
✕ dependency_conflict
✕ timeout
5086MB installed
● package 5086MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GLiNER
✓ from gliner import GLiNER
This quickstart demonstrates how to load a pre-trained GLiNER model and use it to extract named entities from a given text based on a custom list of labels. The `predict_entities` method returns a list of dictionaries, each containing the extracted text, its predicted label, and a confidence score.
from gliner import GLiNER
# Initialize GLiNER with a pre-trained model
# Available models: "urchade/gliner_base", "urchade/gliner_small-v2.1", "urchade/gliner_medium-v2.1", "urchade/gliner_large-v2.1"
model = GLiNER.from_pretrained("urchade/gliner_medium-v2.1")
text = """Cristiano Ronaldo dos Santos Aveiro (Portuguese pronunciation: [kɾiʃˈtjɐnu ʁɔˈnaldu]; born 5 February 1985) is a Portuguese professional footballer who plays as a forward for and captains both Saudi Pro League club Al Nassr and the Portugal national team. Widely regarded as one of the greatest players of all time, Ronaldo has won five Ballon d'Or awards, a record three UEFA Men's Player of the Year Awards, and four European Golden Shoes, the most by a European player."""
# Define the entity labels you want to extract
labels = ["person", "team", "organization", "location", "award", "nationality", "sport", "date"]
# Predict entities
entities = model.predict_entities(text, labels)
# Print the extracted entities
for entity in entities:
print(f"Text: {entity['text']}, Label: {entity['label']}, Score: {entity['score']:.2f}")
Debug
Known issues
gotchaGLiNER requires `transformers>=4.51.3,<5`. This specific version constraint can lead to conflicts when integrating GLiNER into projects that use other machine learning libraries (e.g., `sentence-transformers`) which might require `transformers>=4.57` (or `transformers 5.x`).fixCarefully manage your Python environment with virtual environments or Conda. For complex dependency trees, consider containerization (e.g., Docker) or specialized tools like `sie-bundles` for isolating incompatible `transformers` versions.
affects: 0.2.23 and later
breakingStarting from `v0.2.23`, GLiNER's updated `transformers` dependency (`>=4.57.3`, pulling `transformers 5.x`) breaks deployment on HuggingFace Inference Endpoints due to incompatibility with the `huggingface-inference-toolkit`.fixIf deploying to HuggingFace Inference Endpoints, pin your `gliner` version to `<0.2.23` (e.g., `gliner==0.2.22`). Alternatively, ensure your deployment setup explicitly supports `transformers 5.x` and a compatible `huggingface-inference-toolkit` version.
affects: 0.2.23 and later
gotchaOlder versions of GLiNER (prior to `0.2.25`) contained bugs that could cause crashes related to `apex.amp` imports if `torch` was not installed with CUDA, or issues with ONNX model loading when a `torch` file was unexpectedly absent.fixIt is strongly recommended to upgrade to `gliner>=0.2.25` to benefit from the fixes addressing these import and loading issues.
affects: <0.2.25
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gliner_spacy'
The `gliner-spacy` integration, which allows GLiNER to be used with spaCy, is a separate package and needs to be installed explicitly.
fixpip install gliner-spacy
The checkpoint you are trying to load has model type gliner but Transformers does not recognize this architecture.
This error often indicates an incompatibility between the installed `transformers` library version and the `gliner` model architecture you are trying to load, possibly due to an outdated or overly new `transformers` version.
fixEnsure your `transformers` library is compatible with your `gliner` version. Try upgrading `gliner` itself (`pip install --upgrade gliner`), which should pull in a compatible `transformers` version, or explicitly install a known compatible version of `transformers`.
OSError: We couldn't connect to 'https://huggingface.co' to load this file, couldn't find it in the cached files and it looks like <model_name> is not the path to a directory containing a file named config.json.
The model cannot be loaded from Hugging Face Hub either due to a lack of internet connection or because the model files (like `config.json`) are not present in the specified local directory when attempting to load in offline mode.
fixEnsure you have an active internet connection to download the model, or if working offline, manually download the model to a local directory and ensure `local_files_only=True` is used with the correct path to the downloaded model.
AttributeError: 'list' object has no attribute 'cpu'
This typically occurs when a function or operation expects a PyTorch tensor (which has a `.cpu()` method for moving data to CPU) but receives a standard Python list instead.
fixInspect the data type of the object on which `.cpu()` is being called. If it's a list containing tensors, you need to iterate through the list and apply `.cpu()` to each tensor individually, or ensure the preceding operation produces a single tensor if that's the expectation.
ImportError: cannot import name 'auto' from 'tqdm' OR AttributeError: module 'tqdm' has no attribute 'auto'
This error arises when the `tqdm` library, often used for progress bars, is an older version that does not expose `tqdm.auto` or there's an incompatibility with how it's being imported by `gliner` or its dependencies.
fixUpgrade the `tqdm` library to its latest version using `pip install --upgrade tqdm`. If the issue persists in custom code, ensure `tqdm` is imported correctly, possibly by using `from tqdm import tqdm` and calling `tqdm(...)` directly.
Upgrade
Version history
0.2.26latest on PyPI · released Mar 19, 2026
Audit
Dependencies
huggingface_hubrequiredRequired for model interaction
onnxruntimerequiredCore runtime for inference
sentencepiecerequiredTokenization
torchrequiredDeep learning framework
tqdmrequiredProgress bars
transformersrequiredCore transformer models, with version constraints
onnxruntime-gpuoptionalOptional, for GPU acceleration with ONNX
accelerateoptionalOptional, for distributed training/inference
jieba3optionalOptional, for Chinese tokenization