# What changed in spacy

> 150 changes in spacy 2 to 3 from its official release notes, upgrade guides and advisories: 80 breaking, 5 deprecations, 59 new APIs and options. Each one cited. Sources checked 2026-10-23. HTML: https://unstale.sh/pypi/spacy/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## spacy 3

### Breaking changes

- A component for setting token attributes using match patterns; it replaces language-data tag maps and morph rules. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Pipeline construction and training settings are now defined in config.cfg. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Custom components must be registered with Language.component or Language.factory decorators. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Now accepts a list of patterns as its second argument instead of a variable number of arguments. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Check whether a doc has annotation on a token attribute. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Doc.is_parsed was removed; use Doc.has_annotation. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Doc.is_tagged was removed; use Doc.has_annotation. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Doc.merge was removed; use Doc.retokenize. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Doc.tokens_from_list was removed; use Doc.__init__. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Use exclude=["vocab"] instead of vocab=False on serialization methods. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Removed and replaced by Corpus. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Removed and replaced by Example. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Convert word vectors for use with spaCy; it replaces spacy init-model. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Various keyword arguments across functions and methods are now explicitly keyword-only. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- KnowledgeBase.dump was removed; use KnowledgeBase.to_disk. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Removed and replaced by KnowledgeBase.get_alias_candidates. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- KnowledgeBase.load_bulk was removed; use KnowledgeBase.from_disk. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Pass a string name of the component factory instead of a component function; the method also returns the pipeline component. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Removed and replaced by Language.initialize. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Custom pipeline components need to use the @Language.component or @Language.factory decorator. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Disable a loaded pipeline component without removing it. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Removed in favor of Language.select_pipes, Language.disable_pipe, and Language.enable_pipe. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Enable a loaded pipeline component. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Language.entity was removed; use Language.get_pipe. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Now takes batches of Example objects instead of Docs and GoldParse objects or raw text with annotation dictionaries. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- The verbose argument was removed; use logging at DEBUG level. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Custom pipeline components need to use the @Language.factory or @Language.component decorator. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Initialize a model using a function that returns a sequence of Example objects; this replaces begin_training. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Language.parser was removed; use Language.get_pipe. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Use a context manager to enable or disable specific pipeline components for a block. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Language.tagger was removed; use Language.get_pipe. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Now takes batches of Example objects instead of Docs and GoldParse objects or raw text with annotation dictionaries. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Now accepts a list of patterns as its second argument instead of a variable number of arguments; on_match is an optional keyword argument. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Matcher.pipe was removed because it is not needed. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- A pipeline's meta.json now provides metadata only; it no longer constructs the processing pipeline. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Language-data morph rules were replaced by the AttributeRuler component. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- The n_threads argument was removed from Tokenizer, Matcher, and PhraseMatcher; use n_process. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Now accepts a list of patterns as its second argument instead of a variable number of arguments; on_match is an optional keyword argument. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- PhraseMatcher.pipe was removed because it is not needed. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- The -PRON- indicator for pronoun lemmas has been removed. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- The pronoun-lemma symbol was removed. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- spaCy drops Python 2 support and requires Python 3.6 or later. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- The SentenceSegmenter hook was removed; use user hooks, Sentencizer, or SentenceRecognizer. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Shortcuts such as en are no longer supported; load a pipeline using its full package name. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- SimilarityHook was removed; use user hooks, Sentencizer, or SentenceRecognizer. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Removed and replaced by spacy debug data. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- The debug data command now only takes a config.cfg. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Removed and replaced by spacy init vectors. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- The pretrain command now only takes a config.cfg. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- spacy profile was removed; use spacy debug profile. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Training now takes a config.cfg file rather than many command-line arguments. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- The spacy.gold module is renamed to spacy.training. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- A binary training data format created by serializing a DocBin, representing a collection of Doc objects. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Span.lower was removed. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Span.merge was removed; use Doc.retokenize. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Span.string was removed; use Span.text. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Span.upper was removed. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Language-data tag maps were replaced by the AttributeRuler component. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- The textcat component now supports only mutually exclusive classes, with one predicted class per input; use textcat_multilabel for multi-label classification. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Use this component for multi-label classification; textcat is now limited to mutually exclusive classes. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Token.string was removed; use Token.text. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Now takes batches of Example objects instead of Docs and GoldParse objects or raw text with annotation dictionaries. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- util.get_data_path was removed; symlinks are deprecated and the method is not needed. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- util.set_data_path was removed; symlinks are deprecated and the method is not needed. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)

### Deprecations

- The link command is deprecated; use full pipeline package names explicitly. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Shortcut names for pipelines are deprecated; use full package names explicitly. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- The link command and pipeline package symlinks are deprecated; use full pipeline package names explicitly. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3), [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)

### New APIs and options

- Select whether spacy package builds none, a wheel, or both an sdist and wheel. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A single config file describes training settings and hyperparameters, enabling configurable, repeatable training without hidden defaults. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A new trained German transformer-based pipeline using bert-base-german-cased. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Debug training configurations. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Match patterns within dependency parses using Semgrex operators and an API that follows the token-based Matcher. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Store and access named span groups, including collections of potentially overlapping spans. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A new trained English transformer-based pipeline using roberta-base. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A new trained Spanish transformer-based pipeline using bert-base-spanish-wwm-cased. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A new trained French transformer-based pipeline using camembert-base. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Initialize a starter training configuration. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Fill a starter training configuration with default values. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Generate JSON files for labels in the data to speed up training. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Use this callback to modify tokenizer settings when training from a base model. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Analyze the current pipeline and report component attributes, training scores, and required attributes that are not set. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Register pipeline component factories and define default configuration and metadata. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Experimentally continue training a trained pipeline and initialize rehearsal for components that implement a rehearse method. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A standalone component for rule-based and lookup lemmatization that can be explicitly added and configured. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Component models use a unified API and can serve as sublayers in larger networks, including combinations of implementations from different frameworks. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A trainable component that predicts morphological features. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A suite of CLI commands lets developers clone, run, and manage end-to-end spaCy projects. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Map functions to string names that can be referenced in configuration files. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A trainable pipeline component for sentence segmentation. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- An extension package that adds the ray command to the spaCy CLI for parallel training when installed in the same environment. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Run parallel training with Ray on one or more remote machines. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Provides the Transformer pipeline component for using transformer models, accessing outputs, and aligning tokens. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Access a token’s Lexeme. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Access a token’s morphological analysis. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A base class for trainable pipeline components. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Trained components can be sourced from other pipelines in the training config. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- Use pretrained transformers in spaCy pipelines, share a transformer across components with multi-task learning, and interoperate with PyTorch and HuggingFace transformers. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- A new trained Chinese transformer-based pipeline using bert-base-chinese. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)

### Performance

- Pre-built binary wheels are available for all trained pipeline packages and are more efficient. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)

### Behavior and default changes

- Matcher supports greedy patterns. (3.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v3.0.0)
- spaCy adopts pydantic for data validation, including validation of typed arguments for registered config functions. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)
- Automatically builds an installable sdist; --build can select none, wheel, or sdist,wheel. (3.0.0) — [upgrade guide](https://spacy.io/usage/v3)

## spacy 2

### Breaking changes

- Emoji are split into separate tokens wherever possible. (2.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- Training now explicitly begins with this method, which returns an optimizer to pass to update; it replaces Language.end_training. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2), [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- This replaces the former Language.create_make_doc attribute. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- The Matcher API is revised. (2.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- Patterns are added with a match ID, optional callback and one or more patterns in a single call. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- This replaces Matcher.get_entity. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- This replaces Matcher.has_entity. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Serialization is consistent across objects; containers and pipeline components expose disk and bytes serialization methods, with Pickle support. (2.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- Language-specific data now lives in this submodule, and language data is lazy-loaded when a Language class or model is loaded. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- English language data and Language classes are imported from the new spacy.lang submodule rather than spacy.en. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Calls to spacy.load should no longer use the path keyword argument; use Language.from_disk when loading only binary data. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Strings resolve to hash values instead of state-dependent integer IDs, so mappings match across vocabularies and models. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- This replaces Tagger.tag_names. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- This replaces Token.is_ancestor_of. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Models trained with v1.x input are incompatible with v2.0 and must be retrained. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2), [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- Vector resizing moves from Vocab.resize_vectors to Vectors.resize. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)

### Deprecations

- This attribute is deprecated and should be replaced with Span.is_sent_start. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- This method is deprecated and should be replaced with Doc. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)

### New APIs and options

- This boolean keyword argument accepts an iterator of text-context pairs and returns an iterator of Doc-context tuples. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2), [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- New neural models for tagging, parsing and entity recognition are smaller, more accurate and cheaper to run than the previous generation. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Pipeline components can be functions that receive, modify and return a Doc, allowing custom processing at pipeline stages. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- A list of component names can be passed when loading to disable those pipeline components. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- The dependency and named entity visualizers are now part of spaCy and can serve a web page or generate HTML or SVG, with Jupyter rendering detected automatically. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Extension attributes can add custom attributes, properties and methods to Doc objects. (2.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- Custom attributes, properties and methods can be added to Doc, Token and Span objects. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- The new English model makes about 25% fewer mistakes than its v1.x counterpart and is within 1% of the current state-of-the-art. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Container classes including Language, Doc, Vocab and StringStore now expose a consistent byte-deserialization method supporting the Pickle protocol. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Container classes including Language, Doc, Vocab and StringStore now expose a consistent disk-deserialization method. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Built-in pipeline components can be created by component name, including tagger, parser, ner and textcat. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Pipeline components can be disabled with this method or context manager. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- In addition to Doc and GoldParse sequences, update accepts strings and dictionaries describing annotations. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2), [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- spaCy now supports simple lookup-based lemmatization. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- A matcher for efficiently matching large terminology lists using Doc objects as patterns. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- When creating a vocabulary with spacy init-model, this flag automatically prunes vectors. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- An entry point for the spacy command is provided as an alternative to python -m spacy. (2.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- A blank language can be initialized with this function instead of importing its Language class directly. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Models can be loaded by shortcut link, installed model package name or path, with the Language class selected from model settings. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Extension attributes can add custom attributes, properties and methods to Span objects. (2.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- Strings can be added explicitly to the StringStore with this method. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Text categorization models can be added to pipelines, supporting multiple labels that are not mutually exclusive. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Container classes including Language, Doc, Vocab and StringStore now expose a consistent byte-serialization method supporting the Pickle protocol. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Container classes including Language, Doc, Vocab and StringStore now expose a consistent disk-serialization method. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Extension attributes can add custom attributes, properties and methods to Token objects. (2.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)
- A token’s hash is available through this attribute. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- The new class manages vectors assigned to strings, supports individual assignments and GloVe loading, and can map multiple keys to one table row. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)
- Vectors can be pruned through this new Vocab method. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2)

### Performance

- Batching documents with this method brings a significant performance advantage when processing documents in a row. (2.0.0) — [upgrade guide](https://spacy.io/usage/v2), [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)

### Fixes and other changes

- Token.nbor now raises IndexError correctly. (2.0.0) — [release notes](https://github.com/explosion/spaCy/releases/tag/v2.0.0)