---
id: spacy-alignments
version: "0.9.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# spacy-alignments — A spaCy package for the Rust tokenizations library

License: permissive · Maintenance: active · Downloads: 213.6K/mo

## What it is and what it does

spacy-alignments wraps Yohei Tamura's Rust tokenizations library to solve a core problem in modern NLP: when you use spaCy for linguistic processing and transformer models for semantic understanding, their tokenizers often split text differently, breaking the correspondence between spaCy tokens and transformer subword tokens. This package provides bidirectional alignment mappings—given two tokenization schemes, it computes which tokens in scheme A correspond to which in scheme B and vice versa.

It is designed as a drop-in replacement for the older pytokenizations package, using setuptools-rust to simplify cross-platform binary distribution. The package has no runtime dependencies and compiles to native code, making it fast. It supports Python 3.9–3.12 on macOS, Linux, and Windows, with prebuilt wheels for most platforms; if your platform lacks a wheel, you will need Rust installed to compile from source.

Use it for:

- Align spaCy token spans with BERT or other transformer subword tokens for joint NLP + deep learning pipelines.
- Convert linguistic annotations (POS tags, NER labels) from spaCy tokens to transformer token positions for fine-tuning.
- Map attention weights or hidden states from transformers back to spaCy linguistic units for interpretability.
- Integrate spaCy's rule-based NLP with transformer-based models without losing token-level correspondence.
- Handle multilingual text where spaCy and transformer tokenizers diverge significantly.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Aligns tokenizations between spaCy and transformer models by mapping token boundaries between different tokenization schemes, enabling seamless integration of spaCy NLP pipelines with transformer-based models.

Yes, if you are building a pipeline that combines spaCy and transformer models. The package solves a real integration problem with no runtime dependencies and active maintenance. Medium install friction (potential Rust compilation) is a minor drawback but manageable; prebuilt wheels cover most platforms. No known security issues and permissive MIT license add confidence.

## Install

pip install spacy-alignments
uv add spacy-alignments
poetry add spacy-alignments

## Installing spacy-alignments

Before you install: Medium install friction due to Rust compilation requirement when binary wheels are unavailable for your platform. The package maintains active status with recent releases and supports Python 3.9–3.12 across major operating systems, though you may need to install Rust toolchain if a prebuilt wheel is not available.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal restrictions, making it suitable for both commercial and open-source projects.

Quickstart:

pip install spacy-alignments

import spacy_alignments as tokenizations
a2b, b2a = tokenizations.get_alignments(["å", "BC"], ["abc"])
print(a2b, b2a)  # [[0], [0]], [[0, 1]]

If no binary wheel exists for your platform, you must install Rust to build from source.

Verify before relying:

- Whether this package is actively maintained by Explosion AI or community-driven given the 437 days since last release.
- Specific transformer model compatibility and tested integration scenarios beyond the general spaCy + transformers use case.
- Performance characteristics and alignment accuracy guarantees for edge cases in multilingual or specialized tokenization schemes.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 213.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

tokenization alignment spacy transformers, align token boundaries nlp, spacy transformer token mapping, cross-tokenizer alignment, token boundary conversion, nlp-integration, tokenization, transformers

[View on SkillFed](https://skillfed.io/packages/spacy-alignments) · [View on PyPI](https://pypi.org/project/spacy-alignments/)