Practical overview
When it fits
Use it when a spaCy pipeline needs transformer-derived features, shared-transformer multi-task training, or serialization and packaging of transformer-enabled pipelines.
Who it is for
- Python developers building spaCy NLP pipelines with pretrained transformer models.
- Teams training multiple spaCy components around a shared transformer.
Documented uses
- Use pretrained BERT, RoBERTa, XLNet or GPT-2 models as features in spaCy pipelines.
- Align transformer outputs with spaCy tokenization.
- Train spaCy components with shared transformer representations.
- Customize transformer data saved in spaCy Doc objects and package serialized pipelines.
Requirements & limits
The README provides a pip installation command and states requirements of Python 3.6+, PyTorch 1.5+, and spaCy 3.0+. The repository lists an MIT license.
- This release targets spaCy 3; the README directs users of the earlier spaCy 2-era implementation to the 0.6.x branch.
- Task-specific classification heads are not exposed by the transformer component; for predictions from existing Hugging Face text or token classification models, the README points to spacy-huggingface-pipelines.
- GPU installation instructions depend on the CUDA version.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Install spaCy with transformer support
Install the spaCy transformer package and its dependencies before installing transformer models.
Before you start
- Python 3.6 or later
- PyTorch 1.5 or later
- spaCy 3.0 or later
- For GPU installation, identify the CUDA version with
nvcc --version.
Steps
Install the package with the command below.
pip install 'spacy[transformers]'If installing for a GPU, identify the CUDA version and use the corresponding bracketed CUDA variant, such as
spacy[transformers,cuda92]for CUDA 9.2 orspacy[transformers,cuda100]for CUDA 10.0.Install transformer models only after installing this package.
Expected outcome
The package and its dependencies, including PyTorch and spaCy, are installed for use with spaCy transformer pipelines.
Guide limitations
- The instructions specify minimum versions, not a complete compatibility matrix.
- GPU installation requires choosing the CUDA variant that matches the installed CUDA version.
- This release requires spaCy v3; the v0.6.x branch is identified for the previous library version.
Add a transformer component to a spaCy pipeline
Add the installed transformer component to a spaCy pipeline so it can provide transformer outputs to documents and downstream components.
Before you start
- The
spacy-transformerspackage is installed. - A spaCy language pipeline is available.
Steps
Add the component using
nlp.add_pipe("transformer"), or configurefactory = "transformer"in a training config.Process documents through the pipeline; the component writes transformer data to
Doc._.trf_dataand aligns word-piece tokens with spaCy tokens.Connect subsequent spaCy components to the shared transformer using a
TransformerListenerlayer when they need its outputs as features.
Expected outcome
The pipeline includes a transformer component that exposes transformer outputs on processed documents for downstream use.
Guide limitations
- The transformer component does not provide task-specific text- or token-classification heads for training or inference; it can instead provide features to spaCy components such as
nerortextcat. - The documented component and configuration APIs are for the spaCy v3-era package.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 14 October 2026
- Original website title
- explosion/spacy-transformers · Official homepage title · retained in its source language
Related options
spacy-huggingface-pipelines — The README identifies it as an alternative for incorporating existing Hugging Face text or token classification predictions into spaCy pipelines.