//- 💫 DOCS > USAGE > INSTALL > INSTRUCTIONS +h(3, "pip") pip +badge("https://img.shields.io/pypi/v/spacy.svg?style=flat-square", "https://pypi.python.org/pypi/spacy") p | Using pip, spaCy releases are available as source packages and binary | wheels (as of #[code v2.0.13]). +code(false, "bash"). pip install -U spacy +aside("Download models") | After installation you need to download a language model. For more info | and available models, see the #[+a("/usage/models") docs on models]. +code.o-no-block. python -m spacy download en >>> import spacy >>> nlp = spacy.load('en') p | When using pip it is generally recommended to install packages in a | virtual environment to avoid modifying system state: +code(false, "bash"). python -m venv .env source .env/bin/activate pip install spacy +h(3, "conda") conda +badge("https://anaconda.org/conda-forge/spacy/badges/version.svg", "https://anaconda.org/conda-forge/spacy") p | Thanks to our great community, we've finally re-added conda support. You | can now install spaCy via #[code conda-forge]: +code(false, "bash"). conda install -c conda-forge spacy p | For the feedstock including the build recipe and configuration, check out | #[+a("https://github.com/conda-forge/spacy-feedstock") this repository]. | Improvements and pull requests to the recipe and setup are always | appreciated. +h(3, "upgrading") Upgrading spaCy +aside("Upgrading from v1 to v2") | Although we've tried to keep breaking changes to a minimum, upgrading | from spaCy v1.x to v2.x may still require some changes to your code base. | For details see the sections on | #[+a("/usage/v2#incompat") backwards incompatibilities] and | #[+a("/usage/v2#migrating") migrating]. Also remember to download the new | models, and retrain your own models. p | 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 #[strong 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 | #[strong retrain your models] with the new version. p | As of v2.0, spaCy also provides a #[+api("cli#validate") #[code 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 | #[code python -m] to make sure you're executing the correct version of | spaCy. +code(false, "bash"). pip install -U spacy python -m spacy validate +h(3, "gpu") Run spaCy with GPU +tag-new("2.0.14") p | As of v2.0, spaCy's comes with neural network models that are implemented | in our machine learning library, #[+a(gh("thinc")) Thinc]. For GPU | support, we've been grateful to use the work of | Chainer's #[+a("https://cupy.chainer.org") CuPy] module, which provides | a NumPy-compatible interface for GPU arrays. p | spaCy can be installed on GPU by specifying #[code spacy[cuda]], | #[code spacy[cuda90]], #[code spacy[cuda91]], #[code spacy[cuda92]] or | #[code spacy[cuda10]]. 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 two libraries: | #[+a("https://cupy.chainer.org") #[code cupy]] and | #[+a(gh("thinc_gpu_ops")) #[code thinc_gpu_ops]]. +code(false, "bash"). pip install -U spacy[cuda92] p | Once you have a GPU-enabled installation, the best way to activate it is | to call #[+api("top-level#spacy.prefer_gpu") #[code spacy.prefer_gpu()]] | or #[+api("top-level#spacy.require_gpu") #[code spacy.require_gpu()]] | somewhere in your script before any models have been loaded. | #[code require_gpu] will raise an error if no GPU is available. +code. import spacy spacy.prefer_gpu() nlp = spacy.load('en_core_web_sm') +h(3, "source") Compile from source p | The other way to install spaCy is to clone its | #[+a(gh("spaCy")) 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, | #[+a("https://pip.pypa.io/en/latest/installing/") pip], | #[+a("https://virtualenv.pypa.io/") virtualenv] and | #[+a("https://git-scm.com") git] installed. The compiler part is the | trickiest. How to do that depends on your system. See notes on | #[a(href="#source-ubuntu") Ubuntu], #[a(href="#source-osx") OS X] and | #[a(href="#source-windows") Windows] for details. +code(false, "bash"). python -m pip install -U pip # update pip git clone #{gh("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 p | Compared to regular install via pip, the | #[+src(gh("spaCy", "requirements.txt")) #[code requirements.txt]] | additionally installs developer dependencies such as Cython. See the | the #[+a("#section-quickstart") 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 | #[+a("http://www.fabfile.org/") Fabric] commands: +table(["Command", "Description"]) +row +cell #[code fab env] +cell Create a virtual environment and delete previous one, if it exists. +row +cell #[code fab make] +cell Compile the source. +row +cell #[code fab clean] +cell Remove compiled objects, including the generated C++. +row +cell #[code fab test] +cell Run basic tests, aborting after first failure. p | All commands assume that your virtual environment is located in a | directory #[code .env]. If you're using a different directory, you can | change it via the environment variable #[code VENV_DIR], for example: +code(false, "bash"). VENV_DIR=".custom-env" fab clean make +h(4, "source-ubuntu") Ubuntu p Install system-level dependencies via #[code apt-get]: +code(false, "bash"). sudo apt-get install build-essential python-dev git +h(4, "source-osx") macOS / OS X p | Install a recent version of | #[+a("https://developer.apple.com/xcode/") 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, | #[+a("https://github.com/explosion/spaCy/issues/267") see here]. +h(4, "source-windows") Windows p | Install a version of the | #[+a("https://visualstudio.microsoft.com/visual-cpp-build-tools/") Visual C++ Build Tools] or | #[+a("https://www.visualstudio.com/vs/visual-studio-express/") Visual Studio Express] | that matches the version that was used to compile your Python | interpreter. For official distributions these are: +table([ "Distribution", "Version"]) +row +cell Python 2.7 +cell Visual Studio 2008 +row +cell Python 3.4 +cell Visual Studio 2010 +row +cell Python 3.5+ +cell Visual Studio 2015 +h(3, "tests") Run tests p | spaCy comes with an #[+a(gh("spacy", "spacy/tests")) extensive test suite]. | In order to run the tests, you'll usually want to clone the | #[+a(gh("spacy")) repository] and #[+a("#source") build spaCy from source]. | This will also install the required development dependencies and test | utilities defined in the #[code requirements.txt]. p | Alternatively, you can find out where spaCy is installed and run | #[code pytest] on that directory. Don't forget to also install the | test utilities via spaCy's | #[+a(gh("spacy", "requirements.txt")) #[code requirements.txt]]: +code(false, "bash"). python -c "import os; import spacy; print(os.path.dirname(spacy.__file__))" pip install -r path/to/requirements.txt python -m pytest <spacy-directory> p | Calling #[code pytest] on the spaCy directory will run only the basic | tests. The flags #[code --slow] and #[code --model] are optional and | enable additional tests that take longer or use specific models. +code(false, "bash"). # 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 +infobox("Note on model tests", "⚠️") | The test suite specifies a #[+a(gh("spacy", "spacy/tests/conftest.py")) list of models] | to run the tests on. If a model is not installed, the tests will be | skipped. If all models are installed, the respective tests will run once | for each model. The easiest way to find out which models and model | versions are available in your current environment is to run | #[+a("/api/cli#validate") #[code python -m spacy validate]]. This will | also show whether an installed model is out of date, and how to update it.