spacy-models: how spaCy ships its pipelines through GitHub Releases

What problem the repository solves, and who it is for

A trained NLP pipeline is mostly binary data. The README says this outright: because the models can be very large and consist mostly of binary data, the maintainers cannot provide them as files in a GitHub repository, so they attach them to releases as .whl and .tar.gz files. The repository is therefore a distribution mechanism, not source code you build against. Its purpose is to give spaCy users a public release history and an install path that behaves like any other Python package. The audience is anyone running spaCy who needs tagging, parsing, lemmatization, named entity recognition or sentence segmentation without training a model from scratch. That includes application developers embedding spaCy in a service, researchers who need a reproducible baseline, and teams evaluating whether a small pipeline is good enough before committing to a larger one. If you are training your own pipeline with spaCy's training config, this repository is largely irrelevant to you except as a source of pre-trained starting points.

The naming scheme is the interface

The README states that spaCy expects model packages to follow the convention [lang]_[name], and for the provided pipelines the name splits into three components. Type describes capability: core gives tagging, parsing, lemmatization and named entity recognition; dep gives only tagging, parsing and lemmatization; ent gives only named entity recognition; sent gives only sentence segmentation. Genre describes the training text, for example web for web text or news for news text. Size describes the vector table: sm has no word vectors, md has a reduced table with 20k unique vectors covering roughly 500k words, lg has a large table with about 500k entries. The README works the example through: en_core_web_md is a medium English model trained on written web text (blogs, news, comments) with a tagger, parser, lemmatizer, entity recognizer and a 20k-vector table. This matters more than it looks. Choosing sm versus md is not a speed dial, it is a decision about whether word vectors exist at all, and any downstream code that calls .vector on tokens will behave differently depending on that choice.

Version numbers encode spaCy compatibility, not just model quality

The README defines a model version a.b.c as follows: a is the spaCy major version, b is the spaCy minor version, and c is the model version, where a different c means a different model config, for example training on different data, with different parameters, for different iteration counts, or with different vectors. So en_core_web_sm 3.0.0 and 3.0.1 are both built for spaCy 3.0.x, but 3.1.0 is not. The README points to compatibility.json as the detailed compatibility overview and states that it is the source of spaCy's internal compatibility check, performed when you run the download command. That check is the practical safeguard here: python -m spacy download resolves the best-matching version for your installed spaCy rather than grabbing the newest release blindly. The trade-off is that the mapping lives in a file in this repository, so an offline or air-gapped install loses the check unless you replicate it.

Getting a pipeline installed: the three documented routes

The quickstart gives the primary command, python -m spacy download [model], with en_core_web_sm as the example. The README also documents installing the archive directly with pip, from a local path or a URL: pip install /Users/you/en_core_web_sm-3.0.0.tar.gz, the equivalent .whl path, and the full GitHub release URL form, pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.0.0/en_core_web_sm-3.0.0.tar.gz. The third route is manual: download the archive from the releases page, unpack it, and note that the archive contains a model directory with a nested data directory holding config.cfg, meta.json and the component data. Loading is then spacy.load("en_core_web_sm") or, for older models, importing the package and calling en_core_web_sm.load(). The README notes that the import-then-load form should also work for older models in previous spaCy versions, which is the compatibility escape hatch when spacy.load cannot find a package by name.

Where this distribution model creates friction

The release history shows the cost of the approach. The most recent release listed is en_core_web_hftrf-3.8.1 from March 2026, while the next entries, zh_core_web_trf-3.8.0 and zh_core_web_sm-3.8.0, date from September 2024. That gap is not a defect in itself, but it means the repository's activity is uneven across languages and model types, and a team that needs a current pipeline for a less common language may find the newest artifact for that language is well behind the newest artifact overall. The second friction point is size. The README's own warning is that models can be very large, and the v1.x table lists archives such as fr_depvec_web_lg at 1.33 GB. Pulling that through a CI job on every build is a different engineering problem from installing a small wheel, and the README does not describe a mirroring or caching strategy. Third, the licence field for this repository is not stated in the supplied material, and the v1.x table shows per-model licences varying (CC BY-SA and CC BY-NC appear in the rows shown). Model licences are not uniform, so the licence of the repository and the licence of an individual model package should be treated as separate questions.

What it is not: a registry for your own pipelines

The README describes the manual route for people who want to place data in a custom directory or write their own download script using the URL of the archive file. That is the extension point, and it is deliberately minimal: you host the archive, you point pip at it, and spaCy loads the package by name. What the repository does not provide is a general model registry with search, version resolution across arbitrary publishers, or a hosted artifact store for third-party models. If your team trains domain pipelines and needs to distribute them internally, the pattern the README implies is to publish your own package following the same [lang]_[name] convention and the same archive layout (setup.py, meta.json, and the nested pipeline directory with config.cfg and meta.json). The difference in approach is that spacy-models gives you a curated set of Explosion-trained pipelines with a compatibility file tying them to spaCy versions; a self-hosted index gives you control over content but you own the compatibility mapping and the download tooling. Neither replaces the other, and teams often end up running both.

Maintenance cost and what to check before pinning

The upgrade cost is concentrated in the version triple. Because a and b track spaCy's major and minor versions, upgrading spaCy across a minor boundary means the model package you pinned is no longer the one the download command would resolve. The README's compatibility.json is the file to read before that upgrade, since it is the same source the internal check uses. On the model side, a change in c signals a different training config, so a patch-level bump is not automatically safe to absorb without re-checking outputs. There is also a support boundary: the README states that for older versions (v1.6.0 or below) the download route was python -m spacy.en.download all or python -m spacy.de.download all, and manual installation meant unpacking into spacy/data and loading via spacy.load('en') or spacy.load('de'). Those commands are documented as legacy, so anyone maintaining a v1-era pipeline is on a path the README describes historically rather than as current practice. Licence terms for individual model packages are shown per row in the v1.x table and are not uniform across the entries visible there; check the specific package you install rather than assuming the set is homogeneous. This is a factual observation about the material, not legal advice.

Editorial conclusion

Adopt spacy-models if you need a working spaCy pipeline without training one, and start with python -m spacy download en_core_web_sm to confirm the download path works in your environment. Do not treat it as a model registry for custom or domain-specific pipelines: it holds Explosion's own releases, and the README's manual-install route expects you to point pip at an archive URL you host yourself. Before pinning a version, read compatibility.json for the model's spaCy major and minor, because the version triple encodes that pairing and the download command enforces it. The first thing to verify is which of sm, md or lg your task needs, since only md and lg carry word vectors.

Official sources

1. explosion/spacy-models on GitHub
2. Issues
3. Project website
4. README
5. Releases