pypi / spacy
spacy
What changed in spacy 2 to 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-23.
80 breaking5 deprecations59 new APIs and options2 performance3 behavior and defaults1 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initspacy 3102 changes
Breaking changes 64
A component for setting token attributes using match patterns; it replaces language-data tag maps and morph rules.
Pipeline construction and training settings are now defined in config.cfg.
Custom components must be registered with Language.component or Language.factory decorators.
Now accepts a list of patterns as its second argument instead of a variable number of arguments.
Check whether a doc has annotation on a token attribute.
Doc.is_parsed was removed; use Doc.has_annotation.
Doc.is_tagged was removed; use Doc.has_annotation.
Doc.merge was removed; use Doc.retokenize.
Doc.tokens_from_list was removed; use Doc.__init__.
Use exclude=["vocab"] instead of vocab=False on serialization methods.
Removed and replaced by Corpus.
Removed and replaced by Example.
Convert word vectors for use with spaCy; it replaces spacy init-model.
Various keyword arguments across functions and methods are now explicitly keyword-only.
KnowledgeBase.dump was removed; use KnowledgeBase.to_disk.
Removed and replaced by KnowledgeBase.get_alias_candidates.
KnowledgeBase.load_bulk was removed; use KnowledgeBase.from_disk.
Pass a string name of the component factory instead of a component function; the method also returns the pipeline component.
Removed and replaced by Language.initialize.
Custom pipeline components need to use the @Language.component or @Language.factory decorator.
Disable a loaded pipeline component without removing it.
Removed in favor of Language.select_pipes, Language.disable_pipe, and Language.enable_pipe.
Enable a loaded pipeline component.
Language.entity was removed; use Language.get_pipe.
Now takes batches of Example objects instead of Docs and GoldParse objects or raw text with annotation dictionaries.
The verbose argument was removed; use logging at DEBUG level.
Custom pipeline components need to use the @Language.factory or @Language.component decorator.
Initialize a model using a function that returns a sequence of Example objects; this replaces begin_training.
Language.parser was removed; use Language.get_pipe.
Use a context manager to enable or disable specific pipeline components for a block.
Language.tagger was removed; use Language.get_pipe.
Now takes batches of Example objects instead of Docs and GoldParse objects or raw text with annotation dictionaries.
Now accepts a list of patterns as its second argument instead of a variable number of arguments; on_match is an optional keyword argument.
Matcher.pipe was removed because it is not needed.
A pipeline's meta.json now provides metadata only; it no longer constructs the processing pipeline.
Language-data morph rules were replaced by the AttributeRuler component.
The n_threads argument was removed from Tokenizer, Matcher, and PhraseMatcher; use n_process.
Now accepts a list of patterns as its second argument instead of a variable number of arguments; on_match is an optional keyword argument.
PhraseMatcher.pipe was removed because it is not needed.
The -PRON- indicator for pronoun lemmas has been removed.
The pronoun-lemma symbol was removed.
spaCy drops Python 2 support and requires Python 3.6 or later.
The SentenceSegmenter hook was removed; use user hooks, Sentencizer, or SentenceRecognizer.
Shortcuts such as en are no longer supported; load a pipeline using its full package name.
SimilarityHook was removed; use user hooks, Sentencizer, or SentenceRecognizer.
Removed and replaced by spacy debug data.
The debug data command now only takes a config.cfg.
Removed and replaced by spacy init vectors.
The pretrain command now only takes a config.cfg.
spacy profile was removed; use spacy debug profile.
Training now takes a config.cfg file rather than many command-line arguments.
The spacy.gold module is renamed to spacy.training.
A binary training data format created by serializing a DocBin, representing a collection of Doc objects.
Span.lower was removed.
Span.merge was removed; use Doc.retokenize.
Span.string was removed; use Span.text.
Span.upper was removed.
Language-data tag maps were replaced by the AttributeRuler component.
The textcat component now supports only mutually exclusive classes, with one predicted class per input; use textcat_multilabel for multi-label classification.
Use this component for multi-label classification; textcat is now limited to mutually exclusive classes.
Token.string was removed; use Token.text.
Now takes batches of Example objects instead of Docs and GoldParse objects or raw text with annotation dictionaries.
util.get_data_path was removed; symlinks are deprecated and the method is not needed.
util.set_data_path was removed; symlinks are deprecated and the method is not needed.
Deprecations 3
The link command is deprecated; use full pipeline package names explicitly.
Shortcut names for pipelines are deprecated; use full package names explicitly.
The link command and pipeline package symlinks are deprecated; use full pipeline package names explicitly.
New APIs and options 31
Select whether spacy package builds none, a wheel, or both an sdist and wheel.
A single config file describes training settings and hyperparameters, enabling configurable, repeatable training without hidden defaults.
A new trained German transformer-based pipeline using bert-base-german-cased.
Debug training configurations.
Match patterns within dependency parses using Semgrex operators and an API that follows the token-based Matcher.
Store and access named span groups, including collections of potentially overlapping spans.
A new trained English transformer-based pipeline using roberta-base.
A new trained Spanish transformer-based pipeline using bert-base-spanish-wwm-cased.
A new trained French transformer-based pipeline using camembert-base.
Initialize a starter training configuration.
Fill a starter training configuration with default values.
Generate JSON files for labels in the data to speed up training.
Use this callback to modify tokenizer settings when training from a base model.
Analyze the current pipeline and report component attributes, training scores, and required attributes that are not set.
Register pipeline component factories and define default configuration and metadata.
Experimentally continue training a trained pipeline and initialize rehearsal for components that implement a rehearse method.
A standalone component for rule-based and lookup lemmatization that can be explicitly added and configured.
Component models use a unified API and can serve as sublayers in larger networks, including combinations of implementations from different frameworks.
A trainable component that predicts morphological features.
A suite of CLI commands lets developers clone, run, and manage end-to-end spaCy projects.
Map functions to string names that can be referenced in configuration files.
A trainable pipeline component for sentence segmentation.
An extension package that adds the ray command to the spaCy CLI for parallel training when installed in the same environment.
Run parallel training with Ray on one or more remote machines.
Provides the Transformer pipeline component for using transformer models, accessing outputs, and aligning tokens.
Access a token’s Lexeme.
Access a token’s morphological analysis.
A base class for trainable pipeline components.
Trained components can be sourced from other pipelines in the training config.
Use pretrained transformers in spaCy pipelines, share a transformer across components with multi-task learning, and interoperate with PyTorch and HuggingFace transformers.
A new trained Chinese transformer-based pipeline using bert-base-chinese.
Performance 1
Pre-built binary wheels are available for all trained pipeline packages and are more efficient.
Behavior and default changes 3
Matcher supports greedy patterns.
spaCy adopts pydantic for data validation, including validation of typed arguments for registered config functions.
Automatically builds an installable sdist; --build can select none, wheel, or sdist,wheel.
spacy 248 changes
Breaking changes 16
Emoji are split into separate tokens wherever possible.
Training now explicitly begins with this method, which returns an optimizer to pass to update; it replaces Language.end_training.
This replaces the former Language.create_make_doc attribute.
The Matcher API is revised.
Patterns are added with a match ID, optional callback and one or more patterns in a single call.
This replaces Matcher.get_entity.
This replaces Matcher.has_entity.
Serialization is consistent across objects; containers and pipeline components expose disk and bytes serialization methods, with Pickle support.
Language-specific data now lives in this submodule, and language data is lazy-loaded when a Language class or model is loaded.
English language data and Language classes are imported from the new spacy.lang submodule rather than spacy.en.
Calls to spacy.load should no longer use the path keyword argument; use Language.from_disk when loading only binary data.
Strings resolve to hash values instead of state-dependent integer IDs, so mappings match across vocabularies and models.
This replaces Tagger.tag_names.
This replaces Token.is_ancestor_of.
Models trained with v1.x input are incompatible with v2.0 and must be retrained.
Vector resizing moves from Vocab.resize_vectors to Vectors.resize.
Deprecations 2
This attribute is deprecated and should be replaced with Span.is_sent_start.
This method is deprecated and should be replaced with Doc.
New APIs and options 28
This boolean keyword argument accepts an iterator of text-context pairs and returns an iterator of Doc-context tuples.
New neural models for tagging, parsing and entity recognition are smaller, more accurate and cheaper to run than the previous generation.
Pipeline components can be functions that receive, modify and return a Doc, allowing custom processing at pipeline stages.
A list of component names can be passed when loading to disable those pipeline components.
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.
Extension attributes can add custom attributes, properties and methods to Doc objects.
Custom attributes, properties and methods can be added to Doc, Token and Span objects.
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.
Container classes including Language, Doc, Vocab and StringStore now expose a consistent byte-deserialization method supporting the Pickle protocol.
Container classes including Language, Doc, Vocab and StringStore now expose a consistent disk-deserialization method.
Built-in pipeline components can be created by component name, including tagger, parser, ner and textcat.
Pipeline components can be disabled with this method or context manager.
In addition to Doc and GoldParse sequences, update accepts strings and dictionaries describing annotations.
spaCy now supports simple lookup-based lemmatization.
A matcher for efficiently matching large terminology lists using Doc objects as patterns.
When creating a vocabulary with spacy init-model, this flag automatically prunes vectors.
An entry point for the spacy command is provided as an alternative to python -m spacy.
A blank language can be initialized with this function instead of importing its Language class directly.
Models can be loaded by shortcut link, installed model package name or path, with the Language class selected from model settings.
Extension attributes can add custom attributes, properties and methods to Span objects.
Strings can be added explicitly to the StringStore with this method.
Text categorization models can be added to pipelines, supporting multiple labels that are not mutually exclusive.
Container classes including Language, Doc, Vocab and StringStore now expose a consistent byte-serialization method supporting the Pickle protocol.
Container classes including Language, Doc, Vocab and StringStore now expose a consistent disk-serialization method.
Extension attributes can add custom attributes, properties and methods to Token objects.
A token’s hash is available through this attribute.
The new class manages vectors assigned to strings, supports individual assignments and GloVe loading, and can map multiple keys to one table row.
Vectors can be pruned through this new Vocab method.
Performance 1
Batching documents with this method brings a significant performance advantage when processing documents in a row.
Fixes and other changes 1
Token.nbor now raises IndexError correctly.