Install spaCy

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.

Quickstart

Operating system
Package manager
Python version
Configuration
Models
python -m pip install -U virtualenvpython -m pip install -U venvvirtualenv .envvenv .envsource .env/bin/activatesource .env/bin/activate.env\Scripts\activateexport PATH=$PATH:/usr/local/cuda-8.0/binexport PATH=$PATH:/usr/local/cuda-8.0/binpip install -U spacyconda install -c conda-forge spacygit clone https://github.com/explosion/spaCycd spaCypip install -r requirements.txtpip install -e .python -m spacy download enpython -m spacy download depython -m spacy download frpython -m spacy download es
Like this widget? Check out quickstart.js!

Installation instructions

pip{name} version

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 virtualenv to avoid modifying system state:

virtualenv .env
source .env/bin/activate
pip install spacy

conda{name} version

Thanks to our great community, we've finally re-added conda support. You can now install spaCy via conda-forge:

conda config --add channels conda-forge
conda install 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.

Run spaCy with GPU

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 enviroment 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.

# make sure you are using recent pip/virtualenv versions
python -m pip install -U pip virtualenv
git clone https://github.com/explosion/spaCy
cd spaCy

virtualenv .env
source .env/bin/activate
pip install -r requirements.txt
pip install -e .

Compared to regular install via pip, requirements.txt additionally installs developer dependencies such as Cython.

Instead of the above verbose commands, you can also use the following Fabric commands:

CommandDescription
fab envCreate virtualenv and delete previous one, if it exists.
fab makeCompile the source.
fab cleanRemove compiled objects, including the generated C++.
fab testRun basic tests, aborting after first failure.

All commands assume that your virtualenv 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

Ubuntu

Install system-level dependencies via apt-get:

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.

Windows

Install a version of Visual Studio Express that matches the version that was used to compile your Python interpreter. For official distributions these are:

DistributionVersion
Python 2.7Visual Studio 2008
Python 3.4Visual Studio 2010
Python 3.5+Visual Studio 2015

Troubleshooting guide

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 v1.8).

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 download or link command 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

The 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 pip --version.

Import error

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 shortcut 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.

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. Run the command with python -m, for example python -m spacy download en. For more info on this, see download .

'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 spacy.

Run tests

spaCy comes with an extensive test suite. First, find out where spaCy is installed:

python -c "import os; import spacy; print(os.path.dirname(spacy.__file__))"

Then run pytest on that directory. The flags --slow and --model are optional and enable additional tests.

# 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
Read next: Models