spaCy’s models can be installed as Python packages. This means that they’re
a component of your application, just like any other module. They’re versioned
and can be defined as a dependency in your
requirements.txt. Models can be
installed from a download URL or a local directory, manually or via
pip. Their data can be located anywhere on
your file system.
Install a default model, get the code to load it from within spaCy and an example to test it. For more options, see the section on available models below.
python -m spacy download en_core_web_smimport spacynlp = spacy.load("en_core_web_sm")import en_core_web_smnlp = en_core_web_sm.load()doc = nlp(u"This is a sentence.")print([(w.text, w.pos_) for w in doc])python -m spacy download de_core_news_smimport spacynlp = spacy.load("de_core_news_sm")import de_core_news_smnlp = de_core_news_sm.load()doc = nlp(u"Dies ist ein Satz.")print([(w.text, w.pos_) for w in doc])python -m spacy download fr_core_news_smimport spacynlp = spacy.load("fr_core_news_sm")import fr_core_news_smnlp = fr_core_news_sm.load()doc = nlp(u"C'est une phrase.")print([(w.text, w.pos_) for w in doc])python -m spacy download es_core_news_smimport spacynlp = spacy.load("es_core_news_sm")import es_core_news_smnlp = es_core_news_sm.load()doc = nlp(u"Esto es una frase.")print([(w.text, w.pos_) for w in doc])python -m spacy download pt_core_news_smimport spacynlp = spacy.load("pt_core_news_sm")import pt_core_news_smnlp = pt_core_news_sm.load()doc = nlp(u"Esta é uma frase.")print([(w.text, w.pos_) for w in doc])python -m spacy download it_core_news_smimport spacynlp = spacy.load("it_core_news_sm")import it_core_news_smnlp = it_core_news_sm.load()doc = nlp(u"Questa è una frase.")print([(w.text, w.pos_) for w in doc])python -m spacy download nl_core_news_smimport spacynlp = spacy.load("nl_core_news_sm")import nl_core_news_smnlp = nl_core_news_sm.load()doc = nlp(u"Dit is een zin.")print([(w.text, w.pos_) for w in doc])python -m spacy download el_core_news_smimport spacynlp = spacy.load("el_core_news_sm")import el_core_news_smnlp = el_core_news_sm.load()doc = nlp(u"Αυτή είναι μια πρόταση.")print([(w.text, w.pos_) for w in doc])python -m spacy download xx_ent_wiki_smimport spacynlp = spacy.load("xx_ent_wiki_sm")import xx_ent_wiki_smnlp = xx_ent_wiki_sm.load()doc = nlp(u"This is a sentence about Facebook.")print([(ent.text, ent.label) for ent in doc.ents])
spaCy currently provides support for the following languages. You can help by improving the existing language data and extending the tokenization patterns. See here for details on how to contribute to model development.
|Norwegian Bokmål||none yet|
As of v2.0, spaCy supports models trained on more than one language. This is
especially useful for named entity recognition. The language ID used for
multi-language or language-neutral models is
xx. The language class, a generic
subclass containing only the base language data, can be found in
To load your model with the neutral, multi-language class, simply set
"language": "xx" in your model package’s
meta.json. You can also import the class directly, or call
util.get_lang_class() for lazy-loading.
The easiest way to download a model is via spaCy’s
download command. It takes care of finding the
best-matching model compatible with your spaCy installation.
# Download best-matching version of specific model for your spaCy installation python -m spacy download en_core_web_sm # Out-of-the-box: download best-matching default model and create shortcut link python -m spacy download en # Download exact model version (doesn't create shortcut link) python -m spacy download en_core_web_sm-2.1.0 --direct
The download command will install the model via
pip and place the package in your
pip install spacy python -m spacy download en_core_web_sm
import spacy nlp = spacy.load("en_core_web_sm") doc = nlp(u"This is a sentence.")
To download a model directly using pip,
pip install to the URL or local path of the archive file. To find the
direct link to a model, head over to the
model releases, right
click on the archive link and copy it to your clipboard.
# With external URL pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-2.1.0/en_core_web_sm-2.1.0.tar.gz # With local file pip install /Users/you/en_core_web_sm-2.1.0.tar.gz
By default, this will install the model into your
site-packages directory. You
can then use
spacy.load() to load it via its package name, create a
shortcut link to assign it a custom name, or
import it explicitly as a module. If you need to download
models as part of an automated process, we recommend using pip with a direct
link, instead of relying on spaCy’s
You can also add the direct download link to your application’s
requirements.txt. For more details, see the section on
working with models in production.
In some cases, you might prefer downloading the data manually, for example to place it into a custom directory. You can download the model via your browser from the latest releases, or configure your own download script using the URL of the archive file. The archive consists of a model directory that contains another directory with the model data.
└── en_core_web_md-2.1.0.tar.gz # downloaded archive ├── meta.json # model meta data ├── setup.py # setup file for pip installation └── en_core_web_md # 📦 model package ├── __init__.py # init for pip installation ├── meta.json # model meta data └── en_core_web_md-2.1.0 # model data
You can place the model package directory anywhere on your local file system. To use it with spaCy, assign it a name by creating a shortcut link for the data directory.
To load a model, use
spacy.load with the model’s
shortcut link, package name or a path to the data directory:
import spacy nlp = spacy.load("en_core_web_sm") # load model package "en_core_web_sm" nlp = spacy.load("/path/to/en_core_web_sm") # load package from a directory nlp = spacy.load("en") # load model with shortcut link "en" doc = nlp(u"This is a sentence.")
While previous versions of spaCy required you to maintain a data directory containing the models for each installation, you can now choose how and where you want to keep your data. For example, you could download all models manually and put them into a local directory. Whenever your spaCy projects need a model, you create a shortcut link to tell spaCy to load it from there. This means you’ll never end up with duplicate data.
link command will create a symlink in the
python -m spacy link [package name or path] [shortcut] [--force]
The first argument is the package name (if the model was installed via pip),
or a local path to the the model package. The second argument is the
internal name you want to use for the model. Setting the
--force flag will
overwrite any existing links.
# set up shortcut link to load installed package as "en_default" python -m spacy link en_core_web_md en_default # set up shortcut link to load local model as "my_amazing_model" python -m spacy link /Users/you/model my_amazing_model
If you’ve installed a model via spaCy’s downloader, or directly via pip, you can
import it and then call its
load() method with no arguments:
import en_core_web_sm nlp = en_core_web_sm.load() doc = nlp(u"This is a sentence.")
How you choose to load your models ultimately depends on personal preference.
However, for larger code bases, we usually recommend native imports, as this
will make it easier to integrate models with your existing build process,
continuous integration workflow and testing framework. It’ll also prevent you
from ever trying to load a model that is not installed, as your code will raise
ImportError immediately, instead of failing somewhere down the line when
For more details, see the section on working with models in production.
If you’ve trained your own model, for example for
additional languages or
custom named entities, you can save its state using the
Language.to_disk() method. To make the model more
convenient to deploy, we recommend wrapping it as a Python package.
For more information and a detailed guide on how to package your model, see the documentation on saving and loading models.
If your application depends on one or more models, you’ll usually want to integrate them into your continuous integration workflow and build process. While spaCy provides a range of useful helpers for downloading, linking and loading models, the underlying functionality is entirely based on native Python packages. This allows your application to handle a model like any other package dependency.
For an example of an automated model training and build process, see this overview of how we’re training and packaging our models for spaCy.
download command is mostly intended as a
convenient, interactive wrapper. It performs compatibility checks and prints
detailed error messages and warnings. However, if you’re downloading models as
part of an automated build process, this only adds an unnecessary layer of
complexity. If you know which models your application needs, you should be
specifying them directly.
Because all models are valid Python packages, you can add them to your
requirements.txt. If you’re running your own internal PyPi
installation, you can upload the models there. pip’s
requirements file format
supports both package names to download via a PyPi server, as well as direct
#egg= with the package name tells pip which package to expect from
the download URL. This way, the package won’t be re-downloaded and overwritten
if it’s already installed - just like when you’re downloading a package from
All models are versioned and specify their spaCy dependency. This ensures
cross-compatibility and lets you specify exact version requirements for each
model. If you’ve trained your own model, you can use the
package command to generate the required meta data and
turn it into a loadable package.
Downloading models directly via pip won’t call spaCy’s link
package command, which creates symlinks for model shortcuts.
This means that you’ll have to run this command separately, or use the native
import syntax to load the models:
import en_core_web_sm nlp = en_core_web_sm.load()
In general, this approach is recommended for larger code bases, as it’s more
“native”, and doesn’t depend on symlinks or rely on spaCy’s loader to resolve
string names to model packages. If a model can’t be imported, Python will raise
ImportError immediately. And if a model is imported but not used, any
linter will catch that.
Similarly, it’ll give you more flexibility when writing tests that require
loading models. For example, instead of writing your own
logic around spaCy’s loader, you can use
method to only run a test if a specific model or model version is installed.
Each model package exposes a
__version__ attribute which you can also use to
perform your own version compatibility checks before loading a model.