{"library":"spacy-legacy","title":"spaCy Legacy","description":"spacy-legacy is a Python package that provides outdated registered functions and architectures for spaCy v3.x, ensuring backwards compatibility for projects that rely on older component implementations. It is automatically installed as a dependency of the main spaCy library. The package's releases are typically tied to major spaCy updates where core components undergo backwards-incompatible changes, allowing older configurations and trained models to continue functioning. The current version is 3.0.12, released in January 2023.","status":"active","version":"3.0.12","language":"en","source_language":"en","source_url":"https://github.com/explosion/spacy-legacy","tags":["natural language processing","nlp","spacy","compatibility","legacy","backwards-compatibility"],"install":[{"cmd":"pip install spacy-legacy","lang":"bash","label":"Install `spacy-legacy` (usually installed automatically with `spaCy`)"}],"dependencies":[{"reason":"Provides backward compatibility for spaCy's registered functions and architectures.","package":"spacy","optional":false}],"imports":[{"note":"Users rarely import directly from `spacy-legacy`. Its functions are automatically resolved by `spaCy`'s registry when an older, legacy component name (e.g., `spacy.Tok2Vec.v1`) is used in a configuration file. You can explicitly reference them with the 'spacy-legacy.' prefix in config files.","symbol":"spacy.registry.architectures","correct":"from spacy import registry # Functions are typically resolved via spaCy's registry, not direct import from spacy_legacy"}],"quickstart":{"code":"import spacy\nimport os\nfrom spacy.util import load_config_from_str\n\n# This config uses 'spacy.Tok2Vec.v1', an architecture moved to spacy-legacy\nconfig_content = \"\"\"\n[paths]\nvocab = null # Essential if not using pre-trained vectors, otherwise spacy might expect them\n\n[nlp]\nlang = \"en\"\npipeline = [\"tok2vec\"]\n\n[components]\n[components.tok2vec]\nfactory = \"tok2vec\"\n\n[components.tok2vec.model]\n@architectures = \"spacy.Tok2Vec.v1\"\nwidth = 96\nembed_size = 2000\n\"\"\"\n\n# Save config to a temporary file\nconfig_path = \"temp_legacy_config.cfg\"\nwith open(config_path, \"w\") as f:\n    f.write(config_content)\n\ntry:\n    # spaCy will automatically resolve 'spacy.Tok2Vec.v1' to spacy-legacy's implementation\n    print(f\"Attempting to load pipeline using config from {config_path}...\")\n    nlp = spacy.load(config_path)\n    print(\"Pipeline loaded successfully, leveraging spacy-legacy for 'Tok2Vec.v1'.\")\n\n    doc = nlp(\"This is a demonstration of spacy-legacy in action.\")\n    print(f\"Processed text: {doc.text}\")\n    print(f\"Number of tokens: {len(doc)}\")\n\nexcept Exception as e:\n    print(f\"An error occurred while loading the pipeline: {e}\")\n    print(\"Ensure spacy and spacy-legacy are installed. If spaCy's core architecture\")\n    print(\"for Tok2Vec.v1 has completely changed its signature, this example might need adjustment.\")\nfinally:\n    if os.path.exists(config_path):\n        os.remove(config_path)\n","lang":"python","description":"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."},"warnings":[{"fix":"For 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.","message":"spacy-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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Thoroughly 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]]`).","message":"Older 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.","severity":"breaking","affected_versions":"3.x"},{"fix":"Always run your loaded pipelines against a comprehensive test suite or evaluation data after upgrading `spaCy` to ensure expected behavior and performance.","message":"spaCy 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.","severity":"gotcha","affected_versions":"3.0+"},{"fix":"Upgrade 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.","message":"The `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.","severity":"gotcha","affected_versions":"Versions of `spaCy` that relied on `StaticVectors.v1`"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}