spaCy is compatible with 64-bit CPython 2.6+∕3.3+ and runs on Unix/Linux, macOS/OS X and Windows. The latest spaCy releases are available over pip (source packages only) and conda. Installation requires a working build environment. See notes on Ubuntu, macOS/OS X and Windows for details.
python -m pip install -U virtualenvpython -m pip install -U venvvirtualenv .envpython -m venv .envsource .env/bin/activatesource .env/bin/activate.env\Scripts\activatepip install -U spacyconda install -c conda-forge spacygit clone https://github.com/explosion/spaCycd spaCyexport PYTHONPATH=`pwd`export PYTHONPATH=`pwd`set PYTHONPATH=/path/to/spaCypip install -r requirements.txtpython setup.py build_ext --inplacepython -m spacy download enpython -m spacy download depython -m spacy download espython -m spacy download ptpython -m spacy download frpython -m spacy download itpython -m spacy download nlpython -m spacy download xx
Using pip, spaCy releases are currently only available as source packages.
pip install -U spacy
When using pip it is generally recommended to install packages in a virtual environment to avoid modifying system state:
python -m venv .env source .env/bin/activate pip install spacy
Thanks to our great community, we've finally re-added conda support. You can now install spaCy via
conda install -c conda-forge spacy
For the feedstock including the build recipe and configuration, check out this repository. Improvements and pull requests to the recipe and setup are always appreciated.
When updating to a newer version of spaCy, it's generally recommended to start with a clean virtual environment. If you're upgrading to a new major version, make sure you have the latest compatible models installed, and that there are no old shortcut links or incompatible model packages left over in your environment, as this can often lead to unexpected results and errors. If you've trained your own models, keep in mind that your train and runtime inputs must match. This means you'll have to retrain your models with the new version.
As of v2.0, spaCy also provides a
validate command, which lets you verify that all installed models are compatible
with your spaCy version. If incompatible models are found, tips and
installation instructions are printed. The command is also useful to
detect out-of-sync model links resulting from links created in different
virtual environments. It's recommended to run the command with
python -m to make sure you're executing the correct version of spaCy.
pip install -U spacy python -m spacy validate
Run spaCy with GPUexperimental
As of v2.0, spaCy's comes with neural network models that are implemented in our machine learning library, Thinc. For GPU support, we've been grateful to use the work of Chainer's CuPy module, which provides a NumPy-compatible interface for GPU arrays.
First, install follows the normal CUDA installation procedure. Next, set your environment variables so that the installation will be able to find CUDA. Finally, install spaCy.
export CUDA_HOME=/usr/local/cuda-8.0 # or wherever your CUDA is export PATH=$PATH:$CUDA_HOME/bin pip install spacy python -c "import thinc.neural.gpu_ops" # check the GPU ops were built
Compile from source
The other way to install spaCy is to clone its GitHub repository and build it from source. That is the common way if you want to make changes to the code base. You'll need to make sure that you have a development environment consisting of a Python distribution including header files, a compiler, pip, virtualenv and git installed. The compiler part is the trickiest. How to do that depends on your system. See notes on Ubuntu, OS X and Windows for details.
python -m pip install -U pip # update pip git clone https://github.com/explosion/spaCy # clone spaCy cd spaCy # navigate into directory python -m venv .env # create environment in .env source .env/bin/activate # activate virtual environment export PYTHONPATH=`pwd` # set Python path to spaCy directory pip install -r requirements.txt # install all requirements python setup.py build_ext --inplace # compile spaCy
Compared to regular install via pip, the
requirements.txt additionally installs developer dependencies such as Cython. See the the quickstart widget to get the right commands for your platform and Python version. Instead of the above
verbose commands, you can also use the following Fabric commands:
|Create a virtual environment and delete previous one, if it exists.|
|Compile the source.|
|Remove compiled objects, including the generated C++.|
|Run basic tests, aborting after first failure.|
All commands assume that your virtual environment is located in a directory
.env. If you're using a different directory, you can change it via the environment variable
VENV_DIR, for example:
VENV_DIR=".custom-env" fab clean make
Install system-level dependencies via
sudo apt-get install build-essential python-dev git
macOS / OS X
Install a recent version of XCode, including the so-called "Command Line Tools". macOS and OS X ship with Python and git preinstalled. To compile spaCy with multi-threading support on macOS / OS X, see here.
Install a version of the Visual C++ Build Tools or Visual Studio Express that matches the version that was used to compile your Python interpreter. For official distributions these are:
|Python 2.7||Visual Studio 2008|
|Python 3.4||Visual Studio 2010|
|Python 3.5+||Visual Studio 2015|
spaCy comes with an extensive test suite. In order to run the tests, you'll usually want to clone the repository and build spaCy from source. This will also install the required development dependencies and test utilities defined in the
Alternatively, you can find out where spaCy is installed and run
pytest on that directory. Don't forget to also install the test utilities via spaCy's
python -c "import os; import spacy; print(os.path.dirname(spacy.__file__))" pip install -r path/to/requirements.txt python -m pytest <spacy-directory>
pytest on the spaCy directory will run only the basic tests. The flags
--model are optional and enable additional tests that take longer or use specific models.
# make sure you are using recent pytest version python -m pip install -U pytest python -m pytest <spacy-directory> # basic tests python -m pytest <spacy-directory> --slow # basic and slow tests python -m pytest <spacy-directory> --models --all # basic and all model tests python -m pytest <spacy-directory> --models --en # basic and English model tests
This section collects some of the most common errors you may come across when installing, loading and using spaCy, as well as their solutions.
No compatible model found
No compatible model found for [lang] (spaCy v2.0).
This usually means that the model you're trying to download does not
exist, or isn't available for your version of spaCy. Check the compatibility table to see which models are available for your spaCy version. If you're using
an old version, consider upgrading to the latest release. Note that while
spaCy supports tokenization for a variety of languages, not all of them come with statistical models. To only use the tokenizer, import the language's
Language class instead, for example
from spacy.fr import French.
Symbolic link privilege not held
OSError: symbolic link privilege not held
To create shortcut links that let you load models by name, spaCy creates a symbolic link in the
spacy/data directory. This means your user needs permission to do this. The above error mostly occurs when doing a system-wide installation,
which will create the symlinks in a system directory. Run the
link command as administrator (on Windows, you can either right-click on your terminal or shell ans select "Run as Administrator"), or use a
virtualenv to install spaCy in a user directory, instead of doing a system-wide installation.
No such option: --no-cache-dir
no such option: --no-cache-dir
download command uses pip to install the models and sets the
--no-cache-dir flag to prevent it from requiring too much memory. This setting requires pip v6.0 or newer. Run
pip install -U pip to upgrade to the latest version of pip. To see which version you have installed, run
Unknown locale: UTF-8
ValueError: unknown locale: UTF-8
This error can sometimes occur on OSX and is likely related to a still unresolved Python bug. However, it's easy to fix: just add the following to your
~/.zshrc and then run
source ~/.bash_profile or
source ~/.zshrc. Make sure to add both lines for
export LC_ALL=en_US.UTF-8 export LANG=en_US.UTF-8
Import Error: No module named spacy
This error means that the spaCy module can't be located on your system, or in
your environment. Make sure you have spaCy installed. If you're using a
virtualenv, make sure it's activated and check that spaCy is installed in that environment – otherwise, you're trying to load a system installation. You can also run
which python to find out where your Python executable is located.
Import error: models
ImportError: No module named 'en_core_web_sm'
As of spaCy v1.7, all models can be installed as Python packages. This means
that they'll become importable modules of your application. When creating shortcut links, spaCy will also try to import the model to load its meta data. If this fails, it's usually a
sign that the package is not installed in the current environment. Run
pip list or
pip freeze to check which model packages you have installed, and install the correct models if necessary. If you're importing a model manually at the top of a file, make sure to use the name
of the package, not the shortcut link you've created.
File not found: vocab/strings.json
FileNotFoundError: No such file or directory: [...]/vocab/strings.json
This error may occur when using
spacy.load() to load a language model – either because you haven't set up a shortcut link for it, or because it doesn't actually exist. Set up a link for the model
you want to load. This can either be an installed model package, or a
local directory containing the model data. If you want to use one of the alpha tokenizers for languages that don't yet have a statistical model, you should import its
Language class instead, for example
from spacy.lang.bn import Bengali. You can also use
spacy.blank to create a blank instance, e.g.
nlp = spacy.blank('bn').
Command not found
command not found: spacy
This error may occur when running the
spacy command from the command line. spaCy does not currently add an entry to our
PATH environment variable, as this can lead to unexpected results, especially when using
virtualenv. Instead, spaCy adds an auto-alias that maps
python -m spacy. If this is not working as expected, run the command with
python -m, yourself – for example
python -m spacy download en. For more info on this, see the
'module' object has no attribute 'load'
AttributeError: 'module' object has no attribute 'load'
While this could technically have many causes, including spaCy being
broken, the most likely one is that your script's file or directory name is "shadowing" the module – e.g. your file is called
spacy.py, or a directory you're importing from is called
spacy. So, when using spaCy, never call anything else
Pronoun lemma is returned as
doc = nlp(u'They are') print(doc.lemma_) # -PRON-
This is in fact expected behaviour and not a bug.
Unlike verbs and common nouns, there's no clear base form of a personal
pronoun. Should the lemma of "me" be "I", or should we normalize person
as well, giving "it" — or maybe "he"? spaCy's solution is to introduce a novel symbol,
-PRON-, which is used as the lemma for all personal pronouns. For more info on this, see the lemmatization specs.
NER model doesn't recognise other entities anymore after training
If your training data only contained new entities and you didn't mix in any examples the model previously recognised, it can cause the model to "forget" what it had previously learned. This is also referred to as the "catastrophic forgetting problem". A solution is to pre-label some text, and mix it with the new text in your updates. You can also do this by running spaCy over some text, extracting a bunch of entities the model previously recognised correctly, and adding them to your training examples.
Unhashable type: 'list'
TypeError: unhashable type: 'list'
If you're training models, writing them to disk, and versioning them with
git, you might encounter this error when trying to load them in a Windows
environment. This happens because a default install of Git for Windows is
configured to automatically convert Unix-style end-of-line characters
(LF) to Windows-style ones (CRLF) during file checkout (and the reverse
when commiting). While that's mostly fine for text files, a trained model
written to disk has some binary files that should not go through this
conversion. When they do, you get the error above. You can fix it by either changing your
core.autocrlf setting to
"false", or by commiting a
.gitattributes file to your repository to tell git on which files or folders it shouldn't do LF-to-CRLF conversion, with an entry like
path/to/spacy/model/** -text. After you've done either of these, clone your repository again.