# Note M1 GPU support is experimental, see Thinc issue #792python -m venv .envsource .env/bin/activatesource .env/bin/activate.env\Scripts\activatepython -m venv .envsource .env/bin/activatesource .env/bin/activate.env\Scripts\activateconda create -n venvconda activate venvpip install -U pip setuptools wheelpip install -U pip setuptools wheelpip install -U spacyconda install -c conda-forge spacyconda install -c conda-forge cupyconda install -c conda-forge spacy-transformersgit clone https://github.com/explosion/spaCycd spaCypip install -r requirements.txtpip install --no-build-isolation --editable .# packages only available via pippip install spacy-lookups-datapython -m spacy download ca_core_news_smpython -m spacy download zh_core_web_smpython -m spacy download hr_core_news_smpython -m spacy download da_core_news_smpython -m spacy download nl_core_news_smpython -m spacy download en_core_web_smpython -m spacy download fi_core_news_smpython -m spacy download fr_core_news_smpython -m spacy download de_core_news_smpython -m spacy download el_core_news_smpython -m spacy download it_core_news_smpython -m spacy download ja_core_news_smpython -m spacy download ko_core_news_smpython -m spacy download lt_core_news_smpython -m spacy download mk_core_news_smpython -m spacy download xx_ent_wiki_smpython -m spacy download nb_core_news_smpython -m spacy download pl_core_news_smpython -m spacy download pt_core_news_smpython -m spacy download ro_core_news_smpython -m spacy download ru_core_news_smpython -m spacy download es_core_news_smpython -m spacy download sv_core_news_smpython -m spacy download uk_core_news_sm
spaCy is compatible with 64-bit CPython 3.6+ and runs on Unix/Linux, macOS/OS X and Windows. The latest spaCy releases are available over pip and conda.
Using pip, spaCy releases are available as source packages and binary wheels.
Before you install spaCy and its dependencies, make sure that your
wheel are up to date.
When using pip it is generally recommended to install packages in a virtual environment to avoid modifying system state:
spaCy also lets you install extra dependencies by specifying the following
keywords in brackets, e.g.
multiple comma-separated extras). See the
[options.extras_require] section in
setup.cfg for details on what’s included.
|Install spaCy with GPU support provided by CuPy for your given CUDA version. See the GPU installation instructions for details and options.|
|Install additional dependencies required for tokenization for the languages.|
Thanks to our great community, we’ve been able to re-add conda support. You can
also install spaCy via
For the feedstock including the build recipe and configuration, check out this repository. Note that we currently don’t publish any pre-releases on conda.
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 trained pipelines installed, and that there are no old and incompatible 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 pipelines with the new version.
spaCy also provides a
validate command, which lets you
verify that all installed pipeline packages are compatible with your spaCy
version. If incompatible packages are found, tips and installation instructions
are printed. It’s recommended to run the command with
python -m to make sure
you’re executing the correct version of spaCy.
Run spaCy with GPU
As of v2.0, spaCy 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.
spaCy can be installed for a CUDA-compatible GPU by specifying
spacy[cuda113], etc. If you know your CUDA
version, using the more explicit specifier allows CuPy to be installed via
wheel, saving some compilation time. The specifiers should install
Once you have a GPU-enabled installation, the best way to activate it is to call
spacy.require_gpu() somewhere in your
script before any pipelines have been loaded.
require_gpu will raise an error
if no GPU is available.
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 and git installed. The compiler part is the trickiest. How to do that depends on your system. See notes on Ubuntu, macOS / OS X and Windows for details.
To install with extras:
How to install compilers and related build tools:
- Ubuntu: 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.
- Windows: 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.
Using build constraints when compiling from source
If you install spaCy from source or with
pip for platforms where there are not
binary wheels on PyPI, you may need to use build constraints if any package in
your environment requires an older version of
numpy gets downgraded from the most recent release at any point after
spacy, you might see an error that looks like this:
To fix this, create a new virtual environment and install
spacy and all of its
dependencies using build constraints.
specify an older version of
numpy that is only used while compiling
and then your runtime environment can use any newer version of
numpy and still
be compatible. In addition, use
--no-cache-dir to ignore any previously cached
wheels so that all relevant packages are recompiled from scratch:
Our build constraints currently specify the oldest supported
on PyPI for
aarch64. Depending on your platform and environment,
you may want to customize the specific versions of
numpy. For other platforms,
you can have a look at SciPy’s
package to see what the oldest recommended versions of
(Warning: don’t use
pip install -c constraints.txt instead of
PIP_CONSTRAINT, since this isn’t applied to the isolated build environments.)
Additional options for developers
Some additional options may be useful for spaCy developers who are editing the source code and recompiling frequently.
Install in editable mode. Changes to
.pyfiles will be reflected as soon as the files are saved, but edits to Cython files (
.pyx) will require the
pip installcommand below to be run again. Before installing in editable mode, be sure you have removed any previous installs with
pip uninstall spacy, which you may need to run multiple times to remove all traces of earlier installs.
Build in parallel. Starting in v3.4.0, you can specify the number of build jobs with the environment variable
For editable mode and parallel builds with
python setup.pyinstead of
pip(no longer recommended):
Visual Studio Code extension
The spaCy VSCode Extension provides additional tooling and features for working with spaCy’s config files. Version 1.0.0 includes hover descriptions for registry functions, variables, and section names within the config as an installable extension.
- Install a supported version of Python on your system (
- Install the Python Extension for Visual Studio Code
- Create a virtual python environment
- Install all python requirements (
spaCy >= 3.4.0&
pygls >= 1.0.0)
- Install spaCy extension for Visual Studio Code
- Select your python environment
- You are ready to work with
.cfgfiles in spaCy!
Building an executable
The spaCy repository includes a
builds an executable zip file using
(Python Executable). The executable includes spaCy and all its package
dependencies and only requires the system Python at runtime. Building an
.pex file is often the most convenient way to deploy spaCy, as it
lets you separate the build from the deployment process.
You can configure the build process with the following environment variables:
|Additional Python packages to install alongside spaCy with optional version specifications. Should be a string that can be passed to |
|The Python version to build against. This version needs to be available on your build and runtime machines. Defaults to |
|Directory to store the wheel files during compilation. Defaults to |
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
that directory. Don’t forget to also install the test utilities via spaCy’s
pytest on the spaCy directory will run only the basic tests. The flag
--slow is optional and enables additional tests that take longer.
This section collects some of the most common errors you may come across when installing, loading and using spaCy, as well as their solutions. Also see the Discussions FAQ Thread, which is updated more frequently and covers more transitory issues.
This usually means that the trained pipeline you’re trying to download does not
exist, or isn’t available for your version of spaCy. Check the
to see which packages 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 trained pipelines. To only use the tokenizer, import the
Language class instead, for example
from spacy.lang.fr import French.
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 virtual
environment, 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
which python to find out where your Python executable is located.
As of spaCy v1.7, all trained pipelines can be installed as Python packages.
This means that they’ll become importable modules of your application. If this
fails, it’s usually a sign that the package is not installed in the current
pip list or
pip freeze to check which pipeline packages you
have installed, and install the correct package if necessary. If
you’re importing a package manually at the top of a file, make sure to use the
full name of the package.
This error may occur when running the
spacy command from the command line.
spaCy does not currently add an entry to your
PATH environment variable, as
this can lead to unexpected results, especially when using a virtual
environment. 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_core_web_sm.
For more info on this, see the
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
If your training data only contained new entities and you didn’t mix in any examples the model previously recognized, 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 recognized correctly, and adding them to your training examples.
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
committing). 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
"false", or by committing 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.