Install & Compatibility
Where this runs
tested against v3.0.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.000s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
registry
✓ from spacy_legacy import registry
✗ from spacy_legacy import registry
This quickstart demonstrates how `spacy-legacy` allows spaCy to load configurations that refer to older, deprecated component architectures. When `spaCy` encounters `@architectures = "spacy.Tok2Vec.v1"` in a config, and `v1` is no longer in the core library, `spacy-legacy` provides the necessary implementation, ensuring the pipeline loads without error.
import spacy
import os
from spacy.util import load_config_from_str
# This config uses 'spacy.Tok2Vec.v1', an architecture moved to spacy-legacy
config_content = """
[paths]
vocab = null # Essential if not using pre-trained vectors, otherwise spacy might expect them
[nlp]
lang = "en"
pipeline = ["tok2vec"]
[components]
[components.tok2vec]
factory = "tok2vec"
[components.tok2vec.model]
@architectures = "spacy.Tok2Vec.v1"
width = 96
embed_size = 2000
"""
# Save config to a temporary file
config_path = "temp_legacy_config.cfg"
with open(config_path, "w") as f:
f.write(config_content)
try:
# spaCy will automatically resolve 'spacy.Tok2Vec.v1' to spacy-legacy's implementation
print(f"Attempting to load pipeline using config from {config_path}...")
nlp = spacy.load(config_path)
print("Pipeline loaded successfully, leveraging spacy-legacy for 'Tok2Vec.v1'.")
doc = nlp("This is a demonstration of spacy-legacy in action.")
print(f"Processed text: {doc.text}")
print(f"Number of tokens: {len(doc)}")
except Exception as e:
print(f"An error occurred while loading the pipeline: {e}")
print("Ensure spacy and spacy-legacy are installed. If spaCy's core architecture")
print("for Tok2Vec.v1 has completely changed its signature, this example might need adjustment.")
finally:
if os.path.exists(config_path):
os.remove(config_path)
Debug
Known issues
gotchaspacy-legacy is designed for backward compatibility, not for new development. Avoid explicitly using `spacy-legacy` prefixed functions (e.g., `spacy-legacy.Tok2Vec.v1`) in new configurations, unless you specifically need an older, exact behavior. Always prefer the latest `spaCy` core implementations (e.g., `spacy.Tok2Vec.v2` or later) for optimal performance and features.fixFor new projects or updated components, use current spaCy architectures (e.g., `spacy.Tok2Vec.v2` instead of `spacy.Tok2Vec.v1`). Review spaCy's release notes for migration guides when upgrading.
affects: All versions
breakingOlder spaCy models or configurations explicitly referencing deprecated architectures (like `TextCatBOW.v1` or `MaxoutWindowEncoder.v1`) might behave differently or have different input/output types when loaded with newer spaCy versions. While `spacy-legacy` provides the old implementation, the signature or expected input/output might have changed in core spaCy, leading to runtime errors if not adapted.fixThoroughly test existing pipelines when upgrading `spaCy`. Consult the `spaCy` documentation for specific architecture changes (e.g., `MaxoutWindowEncoder.v1` to `v2` changed output types from `Model[Floats2D, Floats2D]` to `Model[List[Floats2d], List[Floats2d]]`).
affects: 3.x
gotchaspaCy versions 3.0 and newer may issue warnings when loading pipeline packages trained with earlier spaCy v3.x versions. This is a general compatibility warning, even if `spacy-legacy` handles some underlying component differences, and indicates potential subtle incompatibilities.fixAlways run your loaded pipelines against a comprehensive test suite or evaluation data after upgrading `spaCy` to ensure expected behavior and performance.
affects: 3.0+
gotchaThe `spacy.StaticVectors.v1` architecture, available via `spacy-legacy`, contained a bug where tokens without vectors were mapped to the final row in the vectors table. This could cause model predictions to change unexpectedly if new vectors were added to an existing table.fixUpgrade to a `spaCy` version that uses a fixed `StaticVectors` implementation (typically `v2` or later), or if using `v1` explicitly, be aware of this specific behavior.
affects: Versions of `spaCy` that relied on `StaticVectors.v1`
breakingThe `spacy` library is not found. Ensure `spacy` is installed in your environment before attempting to import or use it. This error is typically due to `pip install spacy` not being run or the correct Python environment not being activated.fixInstall `spacy` using `pip install spacy` or ensure your Python environment has `spacy` installed and is properly activated.
affects: All versions
breakingThe `spacy` library was not found in the test environment, resulting in a `ModuleNotFoundError`. This prevents any spaCy-dependent code from executing.fixEnsure `spacy` is correctly installed in the environment where the code is being run. Typically, this is done via `pip install spacy`.
affects: All versions
Upgrade
Version history
3.0.12latest on PyPI · released Jan 23, 2023
Audit
Dependencies
spacyrequiredProvides backward compatibility for spaCy's registered functions and architectures.