🕷️ Crawler Inspector

URL Lookup

Direct Parameter Lookup

Raw Queries and Responses

1. Shard Calculation

Query:

Response:

Calculated Shard: 119 (from laksa016)

2. Crawled Status Check

Query:

Response:

{"found_url":"https:\/\/spacy.io\/usage","crawl_time":1775467772,"first_indexed_time":1510245061,"http_code":200,"src_unparsed":"io,spacy!\/usage s443","src_root_hash":"6839834103567801919","history_drop_reason":null,"meta_title":"Install spaCy · spaCy Usage Documentation","meta_descriptions":["spaCy is a free open-source library for Natural Language Processing in Python. It features NER, POS tagging, dependency parsing, word vectors and more."],"attrs_boilerpipe_text":"Install spaCy\nOperating system\nmacOS \/ OSX\nWindows\nLinux\nPlatform\nx86\nARM \/ M1\nPackage manager\npip\nconda\nfrom source\nHardware\nCPU\nGPU\nConfiguration\nvirtual env\ntrain models\nTrained pipelines\nCatalan\nChinese\nCroatian\nDanish\nDutch\nEnglish\nFinnish\nFrench\nGerman\nGreek\nItalian\nJapanese\nKorean\nLithuanian\nMacedonian\nMulti-language\nNorwegian Bokmål\nPolish\nPortuguese\nRomanian\nRussian\nSlovenian\nSpanish\nSwedish\nUkrainian\nSelect pipeline for\nefficiency\naccuracy\npip install -U pip setuptools wheel\npip install -U spacy\npython -m spacy download en_core_web_sm\nInstallation instructions\nspaCy is compatible with\n64-bit CPython 3.7+\nand runs on\nUnix\/Linux\n,\nmacOS\/OS X\nand\nWindows\n. The latest spaCy releases are available over\npip\nand\nconda\n.\npip\nUsing pip, spaCy releases are available as source packages and binary wheels.\nBefore you install spaCy and its dependencies, make sure that your\npip\n,\nsetuptools\nand\nwheel\nare up to date.\npip install -U pip setuptools wheel\npip install -U spacy\nWhen using pip it is generally recommended to install packages in a virtual\nenvironment to avoid modifying system state:\npython -m venv .env\nsource .env\/bin\/activate\npip install -U pip setuptools wheel\npip install -U spacy\nspaCy also lets you install extra dependencies by specifying the following\nkeywords in brackets, e.g.\nspacy[ja]\nor\nspacy[lookups,transformers]\n(with\nmultiple comma-separated extras). See the\n[options.extras_require]\nsection in\nspaCy’s\nsetup.cfg\nfor details on what’s included.\nName\nDescription\nlookups\nInstall\nspacy-lookups-data\nfor data tables for lemmatization and lexeme normalization. The data is serialized with trained pipelines, so you only need this package if you want to train your own models.\ntransformers\nInstall\nspacy-transformers\n. The package will be installed automatically when you install a transformer-based pipeline.\ncuda\n, …\nInstall spaCy with GPU support provided by\nCuPy\nfor your given CUDA version. See the GPU\ninstallation instructions\nfor details and options.\napple\nInstall\nthinc-apple-ops\nto improve performance on an Apple M1.\nja\n,\nko\n,\nth\nInstall additional dependencies required for tokenization for the\nlanguages\n.\nconda\nThanks to our great community, we’ve been able to re-add conda support. You can\nalso install spaCy via\nconda-forge\n:\nconda install -c conda-forge spacy\nFor the feedstock including the build recipe and configuration, check out\nthis repository\n. Note that we\ncurrently don’t publish any\npre-releases\non conda.\nUpgrading spaCy\nWhen updating to a newer version of spaCy, it’s generally recommended to start\nwith a clean virtual environment. If you’re upgrading to a new major version,\nmake sure you have the latest\ncompatible trained pipelines\ninstalled, and\nthat there are no old and incompatible packages left over in your environment,\nas this can often lead to unexpected results and errors. If you’ve trained your\nown models, keep in mind that your train and runtime inputs must match. This\nmeans you’ll have to\nretrain your pipelines\nwith the new version.\nspaCy also provides a\nvalidate\ncommand, which lets you\nverify that all installed pipeline packages are compatible with your spaCy\nversion. If incompatible packages are found, tips and installation instructions\nare printed. It’s recommended to run the command with\npython -m\nto make sure\nyou’re executing the correct version of spaCy.\npip install -U spacy\npython -m\nspacy\nvalidate\nRun spaCy with GPU\nAs of v2.0, spaCy comes with neural network models that are implemented in our\nmachine learning library,\nThinc\n. For GPU support, we’ve been\ngrateful to use the work of Chainer’s\nCuPy\nmodule,\nwhich provides a numpy-compatible interface for GPU arrays.\nspaCy can be installed for a CUDA-compatible GPU by specifying\nspacy[cuda]\n,\nspacy[cuda102]\n,\nspacy[cuda112]\n,\nspacy[cuda113]\n, etc. If you know your CUDA\nversion, using the more explicit specifier allows CuPy to be installed via\nwheel, saving some compilation time. The specifiers should install\ncupy\n.\npip install -U spacy[cuda113]\nOnce you have a GPU-enabled installation, the best way to activate it is to call\nspacy.prefer_gpu\nor\nspacy.require_gpu()\nsomewhere in your\nscript before any pipelines have been loaded.\nrequire_gpu\nwill raise an error\nif no GPU is available.\nimport\nspacy\nspacy\n.\nprefer_gpu\n(\n)\nnlp\n=\nspacy\n.\nload\n(\n\"en_core_web_sm\"\n)\nCompile from source\nThe other way to install spaCy is to clone its\nGitHub repository\nand build it from\nsource. That is the common way if you want to make changes to the code base.\nYou’ll need to make sure that you have a development environment consisting of a\nPython distribution including header files, a compiler,\npip\nand\ngit\ninstalled.\nThe compiler part is the trickiest. How to do that depends on your system. See\nnotes on\nUbuntu\n,\nmacOS \/ OS X\nand\nWindows\nfor details.\npython -m pip install -U pip setuptools wheel\n# install\/update build tools\ngit clone https:\/\/github.com\/explosion\/spaCy\n# clone spaCy\ncd spaCy\n# navigate into dir\npython -m venv .env\n# create environment in .env\nsource .env\/bin\/activate\n# activate virtual env\npip install -r requirements.txt\n# install requirements\npip install --no-build-isolation --editable .\n# compile and install spaCy\nTo install with extras:\npip install --no-build-isolation --editable .[lookups,cuda102]\nHow to install compilers and related build tools:\nUbuntu:\nInstall system-level dependencies via\napt-get\n:\nsudo apt-get install build-essential python-dev git\nmacOS \/ OS X:\nInstall a recent version of\nXCode\n,\nincluding the so-called “Command Line Tools”. macOS and OS X ship with Python and\nGit preinstalled.\nWindows:\nInstall a version of the\nVisual\nC++ Build Tools\nor\nVisual Studio Express\nthat matches the version that was used to compile your Python interpreter.\nUsing build constraints when compiling from source\nIf you install spaCy from source or with\npip\nfor platforms where there are not\nbinary wheels on PyPI, you may need to use build constraints if any package in\nyour environment requires an older version of\nnumpy\n.\nIf\nnumpy\ngets downgraded from the most recent release at any point after\nyou’ve compiled\nspacy\n, you might see an error that looks like this:\nnumpy.ndarray size changed, may indicate binary incompatibility.\nTo fix this, create a new virtual environment and install\nspacy\nand all of its\ndependencies using build constraints.\nBuild constraints\nspecify an older version of\nnumpy\nthat is only used while compiling\nspacy\n,\nand then your runtime environment can use any newer version of\nnumpy\nand still\nbe compatible. In addition, use\n--no-cache-dir\nto ignore any previously cached\nwheels so that all relevant packages are recompiled from scratch:\nPIP_CONSTRAINT\n=\nhttps:\/\/raw.githubusercontent.com\/explosion\/spacy\/master\/build-constraints.txt\n\\\npip\ninstall\nspacy --no-cache-dir\nOur build constraints currently specify the oldest supported\nnumpy\navailable\non PyPI for\nx86_64\nand\naarch64\n. Depending on your platform and environment,\nyou may want to customize the specific versions of\nnumpy\n. For other platforms,\nyou can have a look at SciPy’s\noldest-supported-numpy\npackage to see what the oldest recommended versions of\nnumpy\nare.\n(\nWarning\n: don’t use\npip install -c constraints.txt\ninstead of\nPIP_CONSTRAINT\n, since this isn’t applied to the isolated build environments.)\nAdditional options for developers\nSome additional options may be useful for spaCy developers who are editing the\nsource code and recompiling frequently.\nInstall in editable mode. Changes to\n.py\nfiles will be reflected as soon as\nthe files are saved, but edits to Cython files (\n.pxd\n,\n.pyx\n) will require\nthe\npip install\ncommand below to be run again. Before installing in editable\nmode, be sure you have removed any previous installs with\npip uninstall spacy\n, which you may need to run multiple times to remove all\ntraces of earlier installs.\npip install -r requirements.txt\npip install --no-build-isolation --editable .\nBuild in parallel. Starting in v3.4.0, you can specify the number of build\njobs with the environment variable\nSPACY_NUM_BUILD_JOBS\n:\npip install -r requirements.txt\nSPACY_NUM_BUILD_JOBS=4 pip install --no-build-isolation --editable .\nFor editable mode and parallel builds with\npython setup.py\ninstead of\npip\n(no longer recommended):\npip install -r requirements.txt\npython setup.py build_ext --inplace -j 4\npython setup.py develop\nVisual Studio Code extension\nThe\nspaCy VSCode Extension\nprovides\nadditional tooling and features for working with spaCy’s config files. Version\n1.0.0 includes hover descriptions for registry functions, variables, and section\nnames within the config as an installable extension.\nInstall a supported version of Python on your system (\n>=3.7\n)\nInstall the\nPython Extension for Visual Studio Code\nCreate a\nvirtual python environment\nInstall all python requirements (\nspaCy >= 3.4.0\n&\npygls >= 1.0.0\n)\nInstall\nspaCy extension for Visual Studio Code\nSelect your python environment\nYou are ready to work with\n.cfg\nfiles in spaCy!\nBuilding an executable\nThe spaCy repository includes a\nMakefile\nthat\nbuilds an executable zip file using\npex\n(\nP\nython\nEx\necutable). The executable includes spaCy and all its package\ndependencies and only requires the system Python at runtime. Building an\nexecutable\n.pex\nfile is often the most convenient way to deploy spaCy, as it\nlets you separate the build from the deployment process.\ngit clone https:\/\/github.com\/explosion\/spaCy\ncd spaCy\nmake\nYou can configure the build process with the following environment variables:\nVariable\nDescription\nSPACY_EXTRAS\nAdditional Python packages to install alongside spaCy with optional version specifications. Should be a string that can be passed to\npip install\n. See\nMakefile\nfor defaults.\nPYVER\nThe Python version to build against. This version needs to be available on your build and runtime machines. Defaults to\n3.8\n.\nWHEELHOUSE\nDirectory to store the wheel files during compilation. Defaults to\n.\/wheelhouse\n.\nRun tests\nspaCy comes with an\nextensive test suite\n. In order\nto run the tests, you’ll usually want to clone the\nrepository\nand\nbuild spaCy from source\n. This will also install the required\ndevelopment dependencies and test utilities defined in the\nrequirements.txt\n.\nAlternatively, you can find out where spaCy is installed and run\npytest\non\nthat directory. Don’t forget to also install the test utilities via spaCy’s\nrequirements.txt\n:\npython -c \"import os; import spacy; print(os.path.dirname(spacy.__file__))\"\npip install -r path\/to\/requirements.txt\npython -m pytest --pyargs spacy\nCalling\npytest\non the spaCy directory will run only the basic tests. The flag\n--slow\nis optional and enables additional tests that take longer.\npython -m pip install -U pytest\n# update pytest\npython -m pytest --pyargs spacy\n# basic tests\npython -m pytest --pyargs spacy --slow\n# basic and slow tests\nTroubleshooting guide\nThis section collects some of the most common errors you may come across when\ninstalling, loading and using spaCy, as well as their solutions. Also see the\nDiscussions FAQ Thread\n,\nwhich is updated more frequently and covers more transitory issues.\nNo compatible package found for [lang] (spaCy vX.X.X).\nThis usually means that the trained pipeline you’re trying to download does not\nexist, or isn’t available for your version of spaCy. Check the\ncompatibility table\nto see which packages are available for your spaCy version. If you’re using an\nold version, consider upgrading to the latest release. Note that while spaCy\nsupports tokenization for\na variety of languages\n, not\nall of them come with trained pipelines. To only use the tokenizer, import the\nlanguage’s\nLanguage\nclass instead, for example\nfrom spacy.lang.fr import French\n.\nImport Error: No module named spacy\nThis error means that the spaCy module can’t be located on your system, or in\nyour environment. Make sure you have spaCy installed. If you’re using a virtual\nenvironment, make sure it’s activated and check that spaCy is installed in that\nenvironment – otherwise, you’re trying to load a system installation. You can\nalso run\nwhich python\nto find out where your Python executable is located.\nImportError: No module named 'en_core_web_sm'\nAs of spaCy v1.7, all trained pipelines can be installed as Python packages.\nThis means that they’ll become importable modules of your application. If this\nfails, it’s usually a sign that the package is not installed in the current\nenvironment. Run\npip list\nor\npip freeze\nto check which pipeline packages you\nhave installed, and install the\ncorrect package\nif necessary. If\nyou’re importing a package manually at the top of a file, make sure to use the\nfull name of the package.\ncommand not found: spacy\nThis error may occur when running the\nspacy\ncommand from the command line.\nspaCy does not currently add an entry to your\nPATH\nenvironment variable, as\nthis can lead to unexpected results, especially when using a virtual\nenvironment. Instead, spaCy adds an auto-alias that maps\nspacy\nto\npython -m spacy\n. If this is not working as expected, run the command with\npython -m\n, yourself – for example\npython -m spacy download en_core_web_sm\n.\nFor more info on this, see the\ndownload\ncommand.\nAttributeError: 'module' object has no attribute 'load'\nWhile this could technically have many causes, including spaCy being broken, the\nmost likely one is that your script’s file or directory name is “shadowing” the\nmodule – e.g. your file is called\nspacy.py\n, or a directory you’re importing\nfrom is called\nspacy\n. So, when using spaCy, never call anything else\nspacy\n.\nIf your training data only contained new entities and you didn’t mix in any\nexamples the model previously recognized, it can cause the model to “forget”\nwhat it had previously learned. This is also referred to as the “catastrophic\nforgetting problem”. A solution is to pre-label some text, and mix it with the\nnew text in your updates. You can also do this by running spaCy over some text,\nextracting a bunch of entities the model previously recognized correctly, and\nadding them to your training examples.\nTypeError: unhashable type: 'list'\nIf you’re training models, writing them to disk, and versioning them with git,\nyou might encounter this error when trying to load them in a Windows\nenvironment. This happens because a default install of Git for Windows is\nconfigured to automatically convert Unix-style end-of-line characters (LF) to\nWindows-style ones (CRLF) during file checkout (and the reverse when\ncommitting). While that’s mostly fine for text files, a trained model written to\ndisk has some binary files that should not go through this conversion. When they\ndo, you get the error above. You can fix it by either changing your\ncore.autocrlf\nsetting to\n\"false\"\n, or by committing a\n.gitattributes\nfile to your\nrepository to tell Git on which files or folders it shouldn’t do LF-to-CRLF\nconversion, with an entry like\npath\/to\/spacy\/model\/** -text\n. After you’ve done\neither of these, clone your repository again.\nChangelog\nStable Releases\nDate\nVersion\nTitle\n2026-03-29\nrelease-v3.8.14\nBug fix for model downloading in environments without pip on PATH\n2026-03-23\nrelease-v3.8.13\nPin confection to new version\n2026-03-23\nrelease-v3.8.12\nv3.8.12\n2025-11-17\nrelease-v3.8.11\nAdd Windows ARM wheels\n2025-11-17\nrelease-v3.8.10\nFix missing Python 3.14 wheels\n2025-11-13\nrelease-v3.8.9\nSupport Python 3.14\n2025-11-07\nrelease-v3.8.8\nFix deprecation warnings, update requirements, drop 3.9\n2025-05-23\nrelease-v3.8.7\nPython 3.13 support, Cython 3, centralize registry entries\n2025-05-19\nrelease-v3.8.6\nRestore wheels, remove Python 3.13 compatibility\n2024-12-11\nrelease-v3.8.3\nImprove memory zone stability\n2024-10-01\nrelease-v3.8.2\nMemory management for persistent services, numpy 2.0 support\n2024-06-05\nv3.7.5\nDownload sanitization, Typer compatibility, and a bugfix for linking gold entities\n2024-02-15\nv3.7.4\nNew textcat layers and fo\/nn language extensions\n2023-10-16\nv3.7.2\nFixes for APIs and requirements\n2023-10-05\nv3.7.1\nBug fix for spacy.cli module loading\n2023-10-02\nv3.7.0\nTrained pipelines using Curated Transformers and support for Python 3.12\n2023-08-08\nv3.6.1\nSupport for Pydantic v2, find-function CLI and more\n2023-07-07\nv3.6.0\nNew span finder component and pipelines for Slovenian\n2023-06-28\nv3.5.4\nBug fixes for overrides with registered functions and sourced components with listeners\n2023-05-25\nv3.3.3\nBug fixes for Pydantic and pip\n2023-05-25\nv3.2.6\nBug fixes for Pydantic and pip\n2023-05-15\nv3.5.3\nSpeed improvements, bug fixes and more\n2023-04-12\nv3.5.2\nPretraining improvements, bug fixes for spans and spancat and more\n2023-03-10\nv3.5.1\nspancat for multi-class labeling, fixes for textcat+transformers and more\n2023-01-20\nv3.5.0\nNew CLI commands, language updates, bug fixes and much more\n2022-12-16\nv3.0.9\nBug fixes and future NumPy compatibility\n2022-12-16\nv2.3.9\nCompatibility with NumPy v1.24+\n2022-12-14\nv3.4.4\nBug fixes and future NumPy compatibility\nPre-Releases\nPre-releases include alpha and beta versions, as well as release candidates. They are not intended for production use. You can download spaCy pre-releases via the\nspacy-nightly\npackage on pip.\nprerelease-v3.8.0.dev0\nprerelease-v3.7.6a","attrs_markdown":"[spaCy](https:\/\/spacy.io\/)\n\n[💥 **New:** spaCy for PDFs and Word docs](https:\/\/github.com\/explosion\/spacy-layout)\n\n- [Usage](https:\/\/spacy.io\/usage)\n- [Models](https:\/\/spacy.io\/models)\n- [API](https:\/\/spacy.io\/api)\n- [Universe](https:\/\/spacy.io\/universe)\n\nSearch\n\n```K`\n\n# Get started\n- Get started\n- [Installation](https:\/\/spacy.io\/usage)\n  - [Quickstart](https:\/\/spacy.io\/usage#quickstart)\n  - [Instructions](https:\/\/spacy.io\/usage#installation)\n  - [Troubleshooting](https:\/\/spacy.io\/usage#troubleshooting)\n  - [Changelog](https:\/\/spacy.io\/usage#changelog)\n- [Models & Languages](https:\/\/spacy.io\/usage\/models)\n- [Facts & Figures](https:\/\/spacy.io\/usage\/facts-figures)\n- [spaCy 101](https:\/\/spacy.io\/usage\/spacy-101)\n- [New in v3.7](https:\/\/spacy.io\/usage\/v3-7)\n- [New in v3.6](https:\/\/spacy.io\/usage\/v3-6)\n- [New in v3.5](https:\/\/spacy.io\/usage\/v3-5)\n\n- Guides\n- [Linguistic Features](https:\/\/spacy.io\/usage\/linguistic-features)\n- [Rule-based Matching](https:\/\/spacy.io\/usage\/rule-based-matching)\n- [Processing Pipelines](https:\/\/spacy.io\/usage\/processing-pipelines)\n- [Embeddings & Transformers](https:\/\/spacy.io\/usage\/embeddings-transformers)\n- [Large Language Models](https:\/\/spacy.io\/usage\/large-language-models)\n- [Training Models](https:\/\/spacy.io\/usage\/training)\n- [Layers & Model Architectures](https:\/\/spacy.io\/usage\/layers-architectures)\n- [spaCy Projects](https:\/\/spacy.io\/usage\/projects)\n- [Saving & Loading](https:\/\/spacy.io\/usage\/saving-loading)\n- [Memory Management](https:\/\/spacy.io\/usage\/memory-management)\n- [Visualizers](https:\/\/spacy.io\/usage\/visualizers)\n\n- Resources\n- [Project Templates](https:\/\/github.com\/explosion\/projects)\n- [v2.x Documentation](https:\/\/v2.spacy.io\/)\n- [Custom Solutions](https:\/\/explosion.ai\/custom-solutions)\n\n# Install spaCy\n#### 📖 Looking for the old docs?\nTo help you make the transition from v2.x to v3.0, we’ve uploaded the old website to [**v2.spacy.io**](https:\/\/v2.spacy.io\/docs). To see what’s changed and how to migrate, see the [v3.0 guide](https:\/\/spacy.io\/usage\/v3).\n\nOperating system\n\nmacOS \/ OSX\n\nWindows\n\nLinux\n\nPlatform\n\nx86\n\nARM \/ M1\n\nPackage manager\n\npip\n\nconda\n\nfrom source\n\nHardware\n\nCPU\n\nGPU\n\nConfiguration\n\nvirtual env\n\ntrain models\n\nTrained pipelines\n\nCatalan\n\nChinese\n\nCroatian\n\nDanish\n\nDutch\n\nEnglish\n\nFinnish\n\nFrench\n\nGerman\n\nGreek\n\nItalian\n\nJapanese\n\nKorean\n\nLithuanian\n\nMacedonian\n\nMulti-language\n\nNorwegian Bokmål\n\nPolish\n\nPortuguese\n\nRomanian\n\nRussian\n\nSlovenian\n\nSpanish\n\nSwedish\n\nUkrainian\n\nSelect pipeline for\n\nefficiency\n\naccuracy\n```\npip install -U pip setuptools wheelpip install -U spacypython -m spacy download en_core_web_sm\n```\n\n## [Installation instructions](https:\/\/spacy.io\/usage#installation)\nspaCy is compatible with **64-bit CPython 3.7+** and runs on **Unix\/Linux**, **macOS\/OS X** and **Windows**. The latest spaCy releases are available over [pip](https:\/\/pypi.python.org\/pypi\/spacy) and [conda](https:\/\/anaconda.org\/conda-forge\/spacy).\n\n### [pip](https:\/\/spacy.io\/usage#pip)\nUsing pip, spaCy releases are available as source packages and binary wheels. Before you install spaCy and its dependencies, make sure that your `pip`, `setuptools` and `wheel` are up to date.\n\n#### Download pipelines\nAfter installation you typically want to download a trained pipeline. For more info and available packages, see the [models directory](https:\/\/spacy.io\/models).\n```\npython -m spacy download en_core_web_sm\n\n>>> import spacy\n>>> nlp = spacy.load(\"en_core_web_sm\")\n```\n```\npip install -U pip setuptools wheel\npip install -U spacy\n```\nWhen using pip it is generally recommended to install packages in a virtual environment to avoid modifying system state:\n```\npython -m venv .env\nsource .env\/bin\/activate\npip install -U pip setuptools wheel\npip install -U spacy\n```\nspaCy also lets you install extra dependencies by specifying the following keywords in brackets, e.g. `spacy[ja]` or `spacy[lookups,transformers]` (with multiple comma-separated extras). See the `[options.extras_require]` section in spaCy’s [`setup.cfg`](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/setup.cfg) for details on what’s included.\n\n#### Example\n```\npip install spacy[lookups,transformers]\n```\n\n| Name | Description |\n|---|---|\n| `lookups` | Install [`spacy-lookups-data`](https:\/\/github.com\/explosion\/spacy-lookups-data) for data tables for lemmatization and lexeme normalization. The data is serialized with trained pipelines, so you only need this package if you want to train your own models. |\n| `transformers` | Install [`spacy-transformers`](https:\/\/github.com\/explosion\/spacy-transformers). The package will be installed automatically when you install a transformer-based pipeline. |\n| `cuda`, … | Install spaCy with GPU support provided by [CuPy](https:\/\/cupy.chainer.org\/) for your given CUDA version. See the GPU [installation instructions](https:\/\/spacy.io\/usage#gpu) for details and options. |\n| `apple` | Install [`thinc-apple-ops`](https:\/\/github.com\/explosion\/thinc-apple-ops) to improve performance on an Apple M1. |\n| `ja`, `ko`, `th` | Install additional dependencies required for tokenization for the [languages](https:\/\/spacy.io\/usage\/models#languages). |\n### [conda](https:\/\/spacy.io\/usage#conda)\nThanks to our great community, we’ve been able to re-add conda support. You can also install spaCy via `conda-forge`:\n```\nconda install -c conda-forge spacy\n```\nFor the feedstock including the build recipe and configuration, check out [this repository](https:\/\/github.com\/conda-forge\/spacy-feedstock). Note that we currently don’t publish any [pre-releases](https:\/\/spacy.io\/usage#changelog-pre) on conda.\n\n### [Upgrading spaCy](https:\/\/spacy.io\/usage#upgrading)\n#### Upgrading from v2 to v3\nAlthough we’ve tried to keep breaking changes to a minimum, upgrading from spaCy v2.x to v3.x may still require some changes to your code base. For details see the sections on [backwards incompatibilities](https:\/\/spacy.io\/usage\/v3#incompat) and [migrating](https:\/\/spacy.io\/usage\/v3#migrating). Also remember to download the new trained pipelines, and retrain your own pipelines.\n\nWhen 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.\n\nspaCy also provides a [`validate`](https:\/\/spacy.io\/api\/cli#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.\n```\npip install -U spacy\npython -m spacy validate\n```\n### [Run spaCy with GPU](https:\/\/spacy.io\/usage#gpu)\nAs of v2.0, spaCy comes with neural network models that are implemented in our machine learning library, [Thinc](https:\/\/thinc.ai\/). For GPU support, we’ve been grateful to use the work of Chainer’s [CuPy](https:\/\/cupy.chainer.org\/) module, which provides a numpy-compatible interface for GPU arrays.\n\nspaCy can be installed for a CUDA-compatible GPU by specifying `spacy[cuda]`, `spacy[cuda102]`, `spacy[cuda112]`, `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 [`cupy`](https:\/\/cupy.chainer.org\/).\n```\npip install -U spacy[cuda113]\n```\nOnce you have a GPU-enabled installation, the best way to activate it is to call [`spacy.prefer_gpu`](https:\/\/spacy.io\/api\/top-level#spacy.prefer_gpu) or [`spacy.require_gpu()`](https:\/\/spacy.io\/api\/top-level#spacy.require_gpu) somewhere in your script before any pipelines have been loaded. `require_gpu` will raise an error if no GPU is available.\n```\nimport spacy\n\nspacy.prefer_gpu()\nnlp = spacy.load(\"en_core_web_sm\")\n```\n### [Compile from source](https:\/\/spacy.io\/usage#source)\nThe other way to install spaCy is to clone its [GitHub repository](https:\/\/github.com\/explosion\/spaCy) 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](https:\/\/pip.pypa.io\/en\/stable\/) and [git](https:\/\/git-scm.com\/) installed. The compiler part is the trickiest. How to do that depends on your system. See notes on [Ubuntu](https:\/\/spacy.io\/usage#source-ubuntu), [macOS \/ OS X](https:\/\/spacy.io\/usage#source-osx) and [Windows](https:\/\/spacy.io\/usage#source-windows) for details.\n```\npython -m pip install -U pip setuptools wheel # install\/update build tools\ngit clone https:\/\/github.com\/explosion\/spaCy  # clone spaCy\ncd spaCy                                      # navigate into dir\npython -m venv .env                           # create environment in .env\nsource .env\/bin\/activate                      # activate virtual env\npip install -r requirements.txt               # install requirements\npip install --no-build-isolation --editable . # compile and install spaCy\n```\nTo install with extras:\n```\npip install --no-build-isolation --editable .[lookups,cuda102]\n```\nHow to install compilers and related build tools:\n\n- **Ubuntu:** Install system-level dependencies via `apt-get`: `sudo apt-get install build-essential python-dev git`\n- **macOS \/ OS X:** Install a recent version of [XCode](https:\/\/developer.apple.com\/xcode\/), including the so-called “Command Line Tools”. macOS and OS X ship with Python and Git preinstalled.\n- **Windows:** Install a version of the [Visual C++ Build Tools](https:\/\/visualstudio.microsoft.com\/visual-cpp-build-tools\/) or [Visual Studio Express](https:\/\/www.visualstudio.com\/vs\/visual-studio-express\/) that matches the version that was used to compile your Python interpreter.\n#### Using build constraints when compiling from source\nIf 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`.\n\nIf `numpy` gets downgraded from the most recent release at any point after you’ve compiled `spacy`, you might see an error that looks like this:\n```\nnumpy.ndarray size changed, may indicate binary incompatibility.\n```\nTo fix this, create a new virtual environment and install `spacy` and all of its dependencies using build constraints. [Build constraints](https:\/\/pip.pypa.io\/en\/stable\/user_guide\/#constraints-files) specify an older version of `numpy` that is only used while compiling `spacy`, 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:\n```\nPIP_CONSTRAINT=https:\/\/raw.githubusercontent.com\/explosion\/spacy\/master\/build-constraints.txt \\\npip install spacy --no-cache-dir\n```\nOur build constraints currently specify the oldest supported `numpy` available on PyPI for `x86_64` and `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 [`oldest-supported-numpy`](https:\/\/github.com\/scipy\/oldest-supported-numpy\/blob\/main\/setup.cfg) package to see what the oldest recommended versions of `numpy` are.\n\n(*Warning*: don’t use `pip install -c constraints.txt` instead of `PIP_CONSTRAINT`, since this isn’t applied to the isolated build environments.)\n\n#### [Additional options for developers](https:\/\/spacy.io\/usage#source-developers)\nSome additional options may be useful for spaCy developers who are editing the source code and recompiling frequently.\n\n- Install in editable mode. Changes to `.py` files will be reflected as soon as the files are saved, but edits to Cython files (`.pxd`, `.pyx`) will require the `pip install` command 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.\n  ```\n  pip install -r requirements.txt\npip install --no-build-isolation --editable .\n  ```\n- Build in parallel. Starting in v3.4.0, you can specify the number of build jobs with the environment variable `SPACY_NUM_BUILD_JOBS`:\n  ```\n  pip install -r requirements.txt\nSPACY_NUM_BUILD_JOBS=4 pip install --no-build-isolation --editable .\n  ```\n- For editable mode and parallel builds with `python setup.py` instead of `pip` (no longer recommended):\n  ```\n  pip install -r requirements.txt\npython setup.py build_ext --inplace -j 4\npython setup.py develop\n  ```\n#### Visual Studio Code extension\n![spaCy extension demo](https:\/\/spacy.io\/images\/spacy-extension-demo.gif)\n\nThe [spaCy VSCode Extension](https:\/\/github.com\/explosion\/spacy-vscode) 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.\n\n1. Install a supported version of Python on your system (`>=3.7`)\n2. Install the [Python Extension for Visual Studio Code](https:\/\/code.visualstudio.com\/docs\/python\/python-tutorial)\n3. Create a [virtual python environment](https:\/\/docs.python.org\/3\/library\/venv.html)\n4. Install all python requirements (`spaCy >= 3.4.0` & `pygls >= 1.0.0`)\n5. Install [spaCy extension for Visual Studio Code](https:\/\/marketplace.visualstudio.com\/items?itemName=Explosion.spacy-extension)\n6. Select your python environment\n7. You are ready to work with `.cfg` files in spaCy\\!\n### [Building an executable](https:\/\/spacy.io\/usage#executable)\nThe spaCy repository includes a [`Makefile`](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/Makefile) that builds an executable zip file using [`pex`](https:\/\/github.com\/pantsbuild\/pex) (**P**ython **Ex**ecutable). The executable includes spaCy and all its package dependencies and only requires the system Python at runtime. Building an executable `.pex` file is often the most convenient way to deploy spaCy, as it lets you separate the build from the deployment process.\n\n#### Usage\nTo use a `.pex` file, just replace `python` with the path to the file when you execute your code or CLI commands. This is equivalent to running Python in a virtual environment with spaCy installed.\n```\n.\/spacy.pex my_script.py\n.\/spacy.pex -m spacy info\n```\n```\ngit clone https:\/\/github.com\/explosion\/spaCy\ncd spaCy\nmake\n```\nYou can configure the build process with the following environment variables:\n\n| Variable | Description |\n|---|---|\n| `SPACY_EXTRAS` | Additional Python packages to install alongside spaCy with optional version specifications. Should be a string that can be passed to `pip install`. See [`Makefile`](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/Makefile) for defaults. |\n| `PYVER` | The Python version to build against. This version needs to be available on your build and runtime machines. Defaults to `3.8`. |\n| `WHEELHOUSE` | Directory to store the wheel files during compilation. Defaults to `.\/wheelhouse`. |\n### [Run tests](https:\/\/spacy.io\/usage#run-tests)\nspaCy comes with an [extensive test suite](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/spacy\/tests). In order to run the tests, you’ll usually want to clone the [repository](https:\/\/github.com\/explosion\/spaCy\/tree\/master) and [build spaCy from source](https:\/\/spacy.io\/usage#source). This will also install the required development dependencies and test utilities defined in the `requirements.txt`.\n\nAlternatively, 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 [`requirements.txt`](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/requirements.txt):\n```\npython -c \"import os; import spacy; print(os.path.dirname(spacy.__file__))\"\npip install -r path\/to\/requirements.txt\npython -m pytest --pyargs spacy\n```\nCalling `pytest` on the spaCy directory will run only the basic tests. The flag `--slow` is optional and enables additional tests that take longer.\n```\npython -m pip install -U pytest               # update pytest\npython -m pytest --pyargs spacy               # basic tests\npython -m pytest --pyargs spacy --slow        # basic and slow tests\n```\n\n## [Troubleshooting guide](https:\/\/spacy.io\/usage#troubleshooting)\nThis 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](https:\/\/github.com\/explosion\/spaCy\/discussions\/8226), which is updated more frequently and covers more transitory issues.\n\n#### Help us improve this guide\nDid you come across a problem like the ones listed here and want to share the solution? You can find the “Suggest edits” button at the bottom of this page that points you to the source. We always appreciate [pull requests](https:\/\/github.com\/explosion\/spaCy\/pulls)\\!\n\n#### No compatible model found\n```\nNo compatible package found for [lang] (spaCy vX.X.X).\n```\nThis 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 [compatibility table](https:\/\/github.com\/explosion\/spacy-models\/tree\/master\/compatibility.json) 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](https:\/\/spacy.io\/usage\/models#languages), not all of them come with trained pipelines. To only use the tokenizer, import the language’s `Language` class instead, for example `from spacy.lang.fr import French`.\n\n#### Import error: No module named spacy\n```\nImport Error: No module named spacy\n```\nThis 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 also run `which python` to find out where your Python executable is located.\n\n#### Import error: No module named \\[name\\]\n```\nImportError: No module named 'en_core_web_sm'\n```\nAs 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 environment. Run `pip list` or `pip freeze` to check which pipeline packages you have installed, and install the [correct package](https:\/\/spacy.io\/models) 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.\n\n#### Command not found: spacy\n```\ncommand not found: spacy\n```\nThis 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 `spacy` to `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 [`download`](https:\/\/spacy.io\/api\/cli#download) command.\n\n#### 'module' object has no attribute 'load'\n```\nAttributeError: 'module' object has no attribute 'load'\n```\nWhile 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`.\n\n#### NER model doesn't recognize other entities anymore after training\nIf 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.\n\n#### Unhashable type: 'list'\n```\nTypeError: unhashable type: 'list'\n```\nIf 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 [`core.autocrlf`](https:\/\/git-scm.com\/book\/en\/v2\/Customizing-Git-Git-Configuration) setting to `\"false\"`, or by committing a [`.gitattributes`](https:\/\/git-scm.com\/docs\/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.\n\n## [Changelog](https:\/\/spacy.io\/usage#changelog)\n### [Stable Releases](https:\/\/spacy.io\/usage#changelog-stable)\n| Date | Version | Title |\n|---|---|---|\n| 2026-03-29 | [`release-v3.8.14`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.14) | Bug fix for model downloading in environments without pip on PATH |\n| 2026-03-23 | [`release-v3.8.13`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.13) | Pin confection to new version |\n| 2026-03-23 | [`release-v3.8.12`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.12) | v3.8.12 |\n| 2025-11-17 | [`release-v3.8.11`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.11) | Add Windows ARM wheels |\n| 2025-11-17 | [`release-v3.8.10`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.10) | Fix missing Python 3.14 wheels |\n| 2025-11-13 | [`release-v3.8.9`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.9) | Support Python 3.14 |\n| 2025-11-07 | [`release-v3.8.8`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.8) | Fix deprecation warnings, update requirements, drop 3.9 |\n| 2025-05-23 | [`release-v3.8.7`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.7) | Python 3.13 support, Cython 3, centralize registry entries |\n| 2025-05-19 | [`release-v3.8.6`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.6) | Restore wheels, remove Python 3.13 compatibility |\n| 2024-12-11 | [`release-v3.8.3`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.3) | Improve memory zone stability |\n| 2024-10-01 | [`release-v3.8.2`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.2) | Memory management for persistent services, numpy 2.0 support |\n| 2024-06-05 | [`v3.7.5`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.7.5) | Download sanitization, Typer compatibility, and a bugfix for linking gold entities |\n| 2024-02-15 | [`v3.7.4`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.7.4) | New textcat layers and fo\/nn language extensions |\n| 2023-10-16 | [`v3.7.2`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.7.2) | Fixes for APIs and requirements |\n| 2023-10-05 | [`v3.7.1`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.7.1) | Bug fix for spacy.cli module loading |\n| 2023-10-02 | [`v3.7.0`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.7.0) | Trained pipelines using Curated Transformers and support for Python 3.12 |\n| 2023-08-08 | [`v3.6.1`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.6.1) | Support for Pydantic v2, find-function CLI and more |\n| 2023-07-07 | [`v3.6.0`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.6.0) | New span finder component and pipelines for Slovenian |\n| 2023-06-28 | [`v3.5.4`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.5.4) | Bug fixes for overrides with registered functions and sourced components with listeners |\n| 2023-05-25 | [`v3.3.3`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.3.3) | Bug fixes for Pydantic and pip |\n| 2023-05-25 | [`v3.2.6`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.2.6) | Bug fixes for Pydantic and pip |\n| 2023-05-15 | [`v3.5.3`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.5.3) | Speed improvements, bug fixes and more |\n| 2023-04-12 | [`v3.5.2`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.5.2) | Pretraining improvements, bug fixes for spans and spancat and more |\n| 2023-03-10 | [`v3.5.1`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.5.1) | spancat for multi-class labeling, fixes for textcat+transformers and more |\n| 2023-01-20 | [`v3.5.0`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.5.0) | New CLI commands, language updates, bug fixes and much more |\n| 2022-12-16 | [`v3.0.9`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.0.9) | Bug fixes and future NumPy compatibility |\n| 2022-12-16 | [`v2.3.9`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v2.3.9) | Compatibility with NumPy v1.24+ |\n| 2022-12-14 | [`v3.4.4`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.4.4) | Bug fixes and future NumPy compatibility |\n### [Pre-Releases](https:\/\/spacy.io\/usage#changelog-pre)\nPre-releases include alpha and beta versions, as well as release candidates. They are not intended for production use. You can download spaCy pre-releases via the [`spacy-nightly`](https:\/\/pypi.org\/packages\/spacy-nightly) package on pip.\n\n[`prerelease-v3.8.0.dev0`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/prerelease-v3.8.0.dev0) [`prerelease-v3.7.6a`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/prerelease-v3.7.6a)\n\n[Suggest edits](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/website\/docs\/usage\/index.mdx)\n\n[Read nextModels & Languages](https:\/\/spacy.io\/usage\/models)\n\n- spaCy\n- [Usage](https:\/\/spacy.io\/usage)\n- [Models](https:\/\/spacy.io\/models)\n- [API Reference](https:\/\/spacy.io\/api)\n- [Online Course](https:\/\/course.spacy.io\/)\n- [Custom Solutions](https:\/\/explosion.ai\/custom-solutions)\n\n- Community\n- [Universe](https:\/\/spacy.io\/universe)\n- [GitHub Discussions](https:\/\/github.com\/explosion\/spaCy\/discussions)\n- [Issue Tracker](https:\/\/github.com\/explosion\/spaCy\/issues)\n- [Stack Overflow](http:\/\/stackoverflow.com\/questions\/tagged\/spacy)\n- [Merchandise](https:\/\/explosion.ai\/merch)\n\n- Connect\n- [Bluesky](https:\/\/bsky.app\/profile\/explosion-ai.bsky.social)\n- [GitHub](https:\/\/github.com\/explosion\/spaCy)\n- [Live Stream](https:\/\/www.youtube.com\/playlist?list=PLBmcuObd5An5_iAxNYLJa_xWmNzsYce8c)\n- [YouTube](https:\/\/youtube.com\/c\/ExplosionAI)\n- [Blog](https:\/\/explosion.ai\/blog)\n\n- Stay in the loop\\!\n- Receive updates about new releases, tutorials and more.\n\n© 2016-2026 [Explosion](https:\/\/explosion.ai\/)\n\n[Legal \/ Imprint](https:\/\/explosion.ai\/legal)","attrs_readable_markdown":"## Install spaCy\nOperating system\n\nmacOS \/ OSXWindowsLinux\n\nPlatform\n\nx86ARM \/ M1\n\nPackage manager\n\npipcondafrom source\n\nHardware\n\nCPUGPU\n\nConfiguration\n\nvirtual envtrain models\n\nTrained pipelines\n\nCatalanChineseCroatianDanishDutchEnglishFinnishFrenchGermanGreekItalianJapaneseKoreanLithuanianMacedonianMulti-languageNorwegian BokmålPolishPortugueseRomanianRussianSlovenianSpanishSwedishUkrainian\n\nSelect pipeline for\n\nefficiencyaccuracy\n```\npip install -U pip setuptools wheelpip install -U spacypython -m spacy download en_core_web_sm\n```\n\n## [Installation instructions](https:\/\/spacy.io\/usage#installation)\nspaCy is compatible with **64-bit CPython 3.7+** and runs on **Unix\/Linux**, **macOS\/OS X** and **Windows**. The latest spaCy releases are available over [pip](https:\/\/pypi.python.org\/pypi\/spacy) and [conda](https:\/\/anaconda.org\/conda-forge\/spacy).\n\n### [pip](https:\/\/spacy.io\/usage#pip)\nUsing pip, spaCy releases are available as source packages and binary wheels. Before you install spaCy and its dependencies, make sure that your `pip`, `setuptools` and `wheel` are up to date.\n```\npip install -U pip setuptools wheel\npip install -U spacy\n```\nWhen using pip it is generally recommended to install packages in a virtual environment to avoid modifying system state:\n```\npython -m venv .env\nsource .env\/bin\/activate\npip install -U pip setuptools wheel\npip install -U spacy\n```\nspaCy also lets you install extra dependencies by specifying the following keywords in brackets, e.g. `spacy[ja]` or `spacy[lookups,transformers]` (with multiple comma-separated extras). See the `[options.extras_require]` section in spaCy’s [`setup.cfg`](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/setup.cfg) for details on what’s included.\n\n| Name | Description |\n|---|---|\n| `lookups` | Install [`spacy-lookups-data`](https:\/\/github.com\/explosion\/spacy-lookups-data) for data tables for lemmatization and lexeme normalization. The data is serialized with trained pipelines, so you only need this package if you want to train your own models. |\n| `transformers` | Install [`spacy-transformers`](https:\/\/github.com\/explosion\/spacy-transformers). The package will be installed automatically when you install a transformer-based pipeline. |\n| `cuda`, … | Install spaCy with GPU support provided by [CuPy](https:\/\/cupy.chainer.org\/) for your given CUDA version. See the GPU [installation instructions](https:\/\/spacy.io\/usage#gpu) for details and options. |\n| `apple` | Install [`thinc-apple-ops`](https:\/\/github.com\/explosion\/thinc-apple-ops) to improve performance on an Apple M1. |\n| `ja`, `ko`, `th` | Install additional dependencies required for tokenization for the [languages](https:\/\/spacy.io\/usage\/models#languages). |\n### [conda](https:\/\/spacy.io\/usage#conda)\nThanks to our great community, we’ve been able to re-add conda support. You can also install spaCy via `conda-forge`:\n```\nconda install -c conda-forge spacy\n```\nFor the feedstock including the build recipe and configuration, check out [this repository](https:\/\/github.com\/conda-forge\/spacy-feedstock). Note that we currently don’t publish any [pre-releases](https:\/\/spacy.io\/usage#changelog-pre) on conda.\n\n### [Upgrading spaCy](https:\/\/spacy.io\/usage#upgrading)\nWhen 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.\n\nspaCy also provides a [`validate`](https:\/\/spacy.io\/api\/cli#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.\n```\npip install -U spacy\npython -m spacy validate\n```\n### [Run spaCy with GPU](https:\/\/spacy.io\/usage#gpu)\nAs of v2.0, spaCy comes with neural network models that are implemented in our machine learning library, [Thinc](https:\/\/thinc.ai\/). For GPU support, we’ve been grateful to use the work of Chainer’s [CuPy](https:\/\/cupy.chainer.org\/) module, which provides a numpy-compatible interface for GPU arrays.\n\nspaCy can be installed for a CUDA-compatible GPU by specifying `spacy[cuda]`, `spacy[cuda102]`, `spacy[cuda112]`, `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 [`cupy`](https:\/\/cupy.chainer.org\/).\n```\npip install -U spacy[cuda113]\n```\nOnce you have a GPU-enabled installation, the best way to activate it is to call [`spacy.prefer_gpu`](https:\/\/spacy.io\/api\/top-level#spacy.prefer_gpu) or [`spacy.require_gpu()`](https:\/\/spacy.io\/api\/top-level#spacy.require_gpu) somewhere in your script before any pipelines have been loaded. `require_gpu` will raise an error if no GPU is available.\n```\nimport spacy\n\nspacy.prefer_gpu()\nnlp = spacy.load(\"en_core_web_sm\")\n```\n### [Compile from source](https:\/\/spacy.io\/usage#source)\nThe other way to install spaCy is to clone its [GitHub repository](https:\/\/github.com\/explosion\/spaCy) 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](https:\/\/pip.pypa.io\/en\/stable\/) and [git](https:\/\/git-scm.com\/) installed. The compiler part is the trickiest. How to do that depends on your system. See notes on [Ubuntu](https:\/\/spacy.io\/usage#source-ubuntu), [macOS \/ OS X](https:\/\/spacy.io\/usage#source-osx) and [Windows](https:\/\/spacy.io\/usage#source-windows) for details.\n```\npython -m pip install -U pip setuptools wheel # install\/update build tools\ngit clone https:\/\/github.com\/explosion\/spaCy  # clone spaCy\ncd spaCy                                      # navigate into dir\npython -m venv .env                           # create environment in .env\nsource .env\/bin\/activate                      # activate virtual env\npip install -r requirements.txt               # install requirements\npip install --no-build-isolation --editable . # compile and install spaCy\n```\nTo install with extras:\n```\npip install --no-build-isolation --editable .[lookups,cuda102]\n```\nHow to install compilers and related build tools:\n\n- **Ubuntu:** Install system-level dependencies via `apt-get`: `sudo apt-get install build-essential python-dev git`\n- **macOS \/ OS X:** Install a recent version of [XCode](https:\/\/developer.apple.com\/xcode\/), including the so-called “Command Line Tools”. macOS and OS X ship with Python and Git preinstalled.\n- **Windows:** Install a version of the [Visual C++ Build Tools](https:\/\/visualstudio.microsoft.com\/visual-cpp-build-tools\/) or [Visual Studio Express](https:\/\/www.visualstudio.com\/vs\/visual-studio-express\/) that matches the version that was used to compile your Python interpreter.\n#### Using build constraints when compiling from source\nIf 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`.\n\nIf `numpy` gets downgraded from the most recent release at any point after you’ve compiled `spacy`, you might see an error that looks like this:\n```\nnumpy.ndarray size changed, may indicate binary incompatibility.\n```\nTo fix this, create a new virtual environment and install `spacy` and all of its dependencies using build constraints. [Build constraints](https:\/\/pip.pypa.io\/en\/stable\/user_guide\/#constraints-files) specify an older version of `numpy` that is only used while compiling `spacy`, 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:\n```\nPIP_CONSTRAINT=https:\/\/raw.githubusercontent.com\/explosion\/spacy\/master\/build-constraints.txt \\\npip install spacy --no-cache-dir\n```\nOur build constraints currently specify the oldest supported `numpy` available on PyPI for `x86_64` and `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 [`oldest-supported-numpy`](https:\/\/github.com\/scipy\/oldest-supported-numpy\/blob\/main\/setup.cfg) package to see what the oldest recommended versions of `numpy` are.\n\n(*Warning*: don’t use `pip install -c constraints.txt` instead of `PIP_CONSTRAINT`, since this isn’t applied to the isolated build environments.)\n\n#### [Additional options for developers](https:\/\/spacy.io\/usage#source-developers)\nSome additional options may be useful for spaCy developers who are editing the source code and recompiling frequently.\n\n- Install in editable mode. Changes to `.py` files will be reflected as soon as the files are saved, but edits to Cython files (`.pxd`, `.pyx`) will require the `pip install` command 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.\n  ```\n  pip install -r requirements.txt\npip install --no-build-isolation --editable .\n  ```\n- Build in parallel. Starting in v3.4.0, you can specify the number of build jobs with the environment variable `SPACY_NUM_BUILD_JOBS`:\n  ```\n  pip install -r requirements.txt\nSPACY_NUM_BUILD_JOBS=4 pip install --no-build-isolation --editable .\n  ```\n- For editable mode and parallel builds with `python setup.py` instead of `pip` (no longer recommended):\n  ```\n  pip install -r requirements.txt\npython setup.py build_ext --inplace -j 4\npython setup.py develop\n  ```\n#### Visual Studio Code extension\n![spaCy extension demo](https:\/\/spacy.io\/images\/spacy-extension-demo.gif)\n\nThe [spaCy VSCode Extension](https:\/\/github.com\/explosion\/spacy-vscode) 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.\n\n1. Install a supported version of Python on your system (`>=3.7`)\n2. Install the [Python Extension for Visual Studio Code](https:\/\/code.visualstudio.com\/docs\/python\/python-tutorial)\n3. Create a [virtual python environment](https:\/\/docs.python.org\/3\/library\/venv.html)\n4. Install all python requirements (`spaCy >= 3.4.0` & `pygls >= 1.0.0`)\n5. Install [spaCy extension for Visual Studio Code](https:\/\/marketplace.visualstudio.com\/items?itemName=Explosion.spacy-extension)\n6. Select your python environment\n7. You are ready to work with `.cfg` files in spaCy\\!\n### [Building an executable](https:\/\/spacy.io\/usage#executable)\nThe spaCy repository includes a [`Makefile`](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/Makefile) that builds an executable zip file using [`pex`](https:\/\/github.com\/pantsbuild\/pex) (**P**ython **Ex**ecutable). The executable includes spaCy and all its package dependencies and only requires the system Python at runtime. Building an executable `.pex` file is often the most convenient way to deploy spaCy, as it lets you separate the build from the deployment process.\n```\ngit clone https:\/\/github.com\/explosion\/spaCy\ncd spaCy\nmake\n```\nYou can configure the build process with the following environment variables:\n\n| Variable | Description |\n|---|---|\n| `SPACY_EXTRAS` | Additional Python packages to install alongside spaCy with optional version specifications. Should be a string that can be passed to `pip install`. See [`Makefile`](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/Makefile) for defaults. |\n| `PYVER` | The Python version to build against. This version needs to be available on your build and runtime machines. Defaults to `3.8`. |\n| `WHEELHOUSE` | Directory to store the wheel files during compilation. Defaults to `.\/wheelhouse`. |\n### [Run tests](https:\/\/spacy.io\/usage#run-tests)\nspaCy comes with an [extensive test suite](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/spacy\/tests). In order to run the tests, you’ll usually want to clone the [repository](https:\/\/github.com\/explosion\/spaCy\/tree\/master) and [build spaCy from source](https:\/\/spacy.io\/usage#source). This will also install the required development dependencies and test utilities defined in the `requirements.txt`.\n\nAlternatively, 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 [`requirements.txt`](https:\/\/github.com\/explosion\/spaCy\/tree\/master\/requirements.txt):\n```\npython -c \"import os; import spacy; print(os.path.dirname(spacy.__file__))\"\npip install -r path\/to\/requirements.txt\npython -m pytest --pyargs spacy\n```\nCalling `pytest` on the spaCy directory will run only the basic tests. The flag `--slow` is optional and enables additional tests that take longer.\n```\npython -m pip install -U pytest               # update pytest\npython -m pytest --pyargs spacy               # basic tests\npython -m pytest --pyargs spacy --slow        # basic and slow tests\n```\n\n## [Troubleshooting guide](https:\/\/spacy.io\/usage#troubleshooting)\nThis 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](https:\/\/github.com\/explosion\/spaCy\/discussions\/8226), which is updated more frequently and covers more transitory issues.\n\n####\n```\nNo compatible package found for [lang] (spaCy vX.X.X).\n```\nThis 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 [compatibility table](https:\/\/github.com\/explosion\/spacy-models\/tree\/master\/compatibility.json) 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](https:\/\/spacy.io\/usage\/models#languages), not all of them come with trained pipelines. To only use the tokenizer, import the language’s `Language` class instead, for example `from spacy.lang.fr import French`.\n\n####\n```\nImport Error: No module named spacy\n```\nThis 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 also run `which python` to find out where your Python executable is located.\n\n####\n```\nImportError: No module named 'en_core_web_sm'\n```\nAs 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 environment. Run `pip list` or `pip freeze` to check which pipeline packages you have installed, and install the [correct package](https:\/\/spacy.io\/models) 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.\n\n####\n```\ncommand not found: spacy\n```\nThis 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 `spacy` to `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 [`download`](https:\/\/spacy.io\/api\/cli#download) command.\n\n####\n```\nAttributeError: 'module' object has no attribute 'load'\n```\nWhile 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`.\n\n####\nIf 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.\n\n####\n```\nTypeError: unhashable type: 'list'\n```\nIf 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 [`core.autocrlf`](https:\/\/git-scm.com\/book\/en\/v2\/Customizing-Git-Git-Configuration) setting to `\"false\"`, or by committing a [`.gitattributes`](https:\/\/git-scm.com\/docs\/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.\n\n## [Changelog](https:\/\/spacy.io\/usage#changelog)\n### [Stable Releases](https:\/\/spacy.io\/usage#changelog-stable)\n| Date | Version | Title |\n|---|---|---|\n| 2026-03-29 | [`release-v3.8.14`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.14) | Bug fix for model downloading in environments without pip on PATH |\n| 2026-03-23 | [`release-v3.8.13`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.13) | Pin confection to new version |\n| 2026-03-23 | [`release-v3.8.12`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.12) | v3.8.12 |\n| 2025-11-17 | [`release-v3.8.11`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.11) | Add Windows ARM wheels |\n| 2025-11-17 | [`release-v3.8.10`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.10) | Fix missing Python 3.14 wheels |\n| 2025-11-13 | [`release-v3.8.9`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.9) | Support Python 3.14 |\n| 2025-11-07 | [`release-v3.8.8`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.8) | Fix deprecation warnings, update requirements, drop 3.9 |\n| 2025-05-23 | [`release-v3.8.7`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.7) | Python 3.13 support, Cython 3, centralize registry entries |\n| 2025-05-19 | [`release-v3.8.6`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.6) | Restore wheels, remove Python 3.13 compatibility |\n| 2024-12-11 | [`release-v3.8.3`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.3) | Improve memory zone stability |\n| 2024-10-01 | [`release-v3.8.2`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/release-v3.8.2) | Memory management for persistent services, numpy 2.0 support |\n| 2024-06-05 | [`v3.7.5`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.7.5) | Download sanitization, Typer compatibility, and a bugfix for linking gold entities |\n| 2024-02-15 | [`v3.7.4`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.7.4) | New textcat layers and fo\/nn language extensions |\n| 2023-10-16 | [`v3.7.2`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.7.2) | Fixes for APIs and requirements |\n| 2023-10-05 | [`v3.7.1`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.7.1) | Bug fix for spacy.cli module loading |\n| 2023-10-02 | [`v3.7.0`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.7.0) | Trained pipelines using Curated Transformers and support for Python 3.12 |\n| 2023-08-08 | [`v3.6.1`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.6.1) | Support for Pydantic v2, find-function CLI and more |\n| 2023-07-07 | [`v3.6.0`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.6.0) | New span finder component and pipelines for Slovenian |\n| 2023-06-28 | [`v3.5.4`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.5.4) | Bug fixes for overrides with registered functions and sourced components with listeners |\n| 2023-05-25 | [`v3.3.3`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.3.3) | Bug fixes for Pydantic and pip |\n| 2023-05-25 | [`v3.2.6`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.2.6) | Bug fixes for Pydantic and pip |\n| 2023-05-15 | [`v3.5.3`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.5.3) | Speed improvements, bug fixes and more |\n| 2023-04-12 | [`v3.5.2`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.5.2) | Pretraining improvements, bug fixes for spans and spancat and more |\n| 2023-03-10 | [`v3.5.1`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.5.1) | spancat for multi-class labeling, fixes for textcat+transformers and more |\n| 2023-01-20 | [`v3.5.0`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.5.0) | New CLI commands, language updates, bug fixes and much more |\n| 2022-12-16 | [`v3.0.9`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.0.9) | Bug fixes and future NumPy compatibility |\n| 2022-12-16 | [`v2.3.9`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v2.3.9) | Compatibility with NumPy v1.24+ |\n| 2022-12-14 | [`v3.4.4`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/v3.4.4) | Bug fixes and future NumPy compatibility |\n### [Pre-Releases](https:\/\/spacy.io\/usage#changelog-pre)\nPre-releases include alpha and beta versions, as well as release candidates. They are not intended for production use. You can download spaCy pre-releases via the [`spacy-nightly`](https:\/\/pypi.org\/packages\/spacy-nightly) package on pip.\n\n[`prerelease-v3.8.0.dev0`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/prerelease-v3.8.0.dev0) [`prerelease-v3.7.6a`](https:\/\/github.com\/explosion\/spaCy\/releases\/tag\/prerelease-v3.7.6a)","meta_canonical":null}

3. Robots.txt Check

Query:

Response:

4. Spam/Ban Check

Query:

Response:

5. Seen Status Check

ℹ️ Skipped - page is already crawled

📄

INDEXABLE

✅

CRAWLED

19 hours ago

🤖

ROBOTS ALLOWED

Page Info Filters

Filter	Status	Condition	Details
HTTP status	PASS	`download_http_code = 200`	HTTP 200
Age cutoff	PASS	`download_stamp > now() - 6 MONTH`	0 months ago
History drop	PASS	`isNull(history_drop_reason)`	No drop reason
Spam/ban	PASS	`fh_dont_index != 1 AND ml_spam_score = 0`	ml_spam_score=0
Canonical	PASS	`meta_canonical IS NULL OR = '' OR = src_unparsed`	Not set

Page Details

Property	Value
URL	https://spacy.io/usage
Last Crawled	2026-04-06 09:29:32 (19 hours ago)
First Indexed	2017-11-09 16:31:01 (8 years ago)
HTTP Status Code	200
Meta Title	Install spaCy · spaCy Usage Documentation
Meta Description	spaCy is a free open-source library for Natural Language Processing in Python. It features NER, POS tagging, dependency parsing, word vectors and more.
Meta Canonical	null
Boilerpipe Text	Install spaCy Operating system macOS / OSX Windows Linux Platform x86 ARM / M1 Package manager pip conda from source Hardware CPU GPU Configuration virtual env train models Trained pipelines Catalan Chinese Croatian Danish Dutch English Finnish French German Greek Italian Japanese Korean Lithuanian Macedonian Multi-language Norwegian Bokmål Polish Portuguese Romanian Russian Slovenian Spanish Swedish Ukrainian Select pipeline for efficiency accuracy pip install -U pip setuptools wheel pip install -U spacy python -m spacy download en_core_web_sm Installation instructions spaCy is compatible with 64-bit CPython 3.7+ and runs on Unix/Linux , macOS/OS X and Windows . The latest spaCy releases are available over pip and conda . pip Using pip, spaCy releases are available as source packages and binary wheels. Before you install spaCy and its dependencies, make sure that your pip , setuptools and wheel are up to date. pip install -U pip setuptools wheel 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 -U pip setuptools wheel pip install -U spacy spaCy also lets you install extra dependencies by specifying the following keywords in brackets, e.g. spacy[ja] or spacy[lookups,transformers] (with multiple comma-separated extras). See the [options.extras_require] section in spaCy’s setup.cfg for details on what’s included. Name Description lookups Install spacy-lookups-data for data tables for lemmatization and lexeme normalization. The data is serialized with trained pipelines, so you only need this package if you want to train your own models. transformers Install spacy-transformers . The package will be installed automatically when you install a transformer-based pipeline. cuda , … Install spaCy with GPU support provided by CuPy for your given CUDA version. See the GPU installation instructions for details and options. apple Install thinc-apple-ops to improve performance on an Apple M1. ja , ko , th Install additional dependencies required for tokenization for the languages . conda Thanks to our great community, we’ve been able to re-add conda support. You can also install spaCy via conda-forge : conda install -c conda-forge spacy 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. Upgrading spaCy 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. pip install -U spacy python -m spacy validate 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[cuda] , spacy[cuda102] , spacy[cuda112] , 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 cupy . pip install -U spacy[cuda113] Once you have a GPU-enabled installation, the best way to activate it is to call spacy.prefer_gpu or spacy.require_gpu() somewhere in your script before any pipelines have been loaded. require_gpu will raise an error if no GPU is available. import spacy spacy . prefer_gpu ( ) nlp = spacy . load ( "en_core_web_sm" ) 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. python -m pip install -U pip setuptools wheel # install/update build tools git clone https://github.com/explosion/spaCy # clone spaCy cd spaCy # navigate into dir python -m venv .env # create environment in .env source .env/bin/activate # activate virtual env pip install -r requirements.txt # install requirements pip install --no-build-isolation --editable . # compile and install spaCy To install with extras: pip install --no-build-isolation --editable .[lookups,cuda102] How to install compilers and related build tools: 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. 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 . If numpy gets downgraded from the most recent release at any point after you’ve compiled spacy , you might see an error that looks like this: numpy.ndarray size changed, may indicate binary incompatibility. To fix this, create a new virtual environment and install spacy and all of its dependencies using build constraints. Build constraints specify an older version of numpy that is only used while compiling spacy , 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: PIP_CONSTRAINT = https://raw.githubusercontent.com/explosion/spacy/master/build-constraints.txt \ pip install spacy --no-cache-dir Our build constraints currently specify the oldest supported numpy available on PyPI for x86_64 and 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 oldest-supported-numpy package to see what the oldest recommended versions of numpy are. ( 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 .py files will be reflected as soon as the files are saved, but edits to Cython files ( .pxd , .pyx ) will require the pip install command 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. pip install -r requirements.txt pip install --no-build-isolation --editable . Build in parallel. Starting in v3.4.0, you can specify the number of build jobs with the environment variable SPACY_NUM_BUILD_JOBS : pip install -r requirements.txt SPACY_NUM_BUILD_JOBS=4 pip install --no-build-isolation --editable . For editable mode and parallel builds with python setup.py instead of pip (no longer recommended): pip install -r requirements.txt python setup.py build_ext --inplace -j 4 python setup.py develop 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 ( >=3.7 ) 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 .cfg files in spaCy! Building an executable The spaCy repository includes a Makefile that builds an executable zip file using pex ( P ython Ex ecutable). The executable includes spaCy and all its package dependencies and only requires the system Python at runtime. Building an executable .pex file is often the most convenient way to deploy spaCy, as it lets you separate the build from the deployment process. git clone https://github.com/explosion/spaCy cd spaCy make You can configure the build process with the following environment variables: Variable Description SPACY_EXTRAS Additional Python packages to install alongside spaCy with optional version specifications. Should be a string that can be passed to pip install . See Makefile for defaults. PYVER The Python version to build against. This version needs to be available on your build and runtime machines. Defaults to 3.8 . WHEELHOUSE Directory to store the wheel files during compilation. Defaults to ./wheelhouse . Run tests 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 requirements.txt . 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 requirements.txt : python -c "import os; import spacy; print(os.path.dirname(spacy.__file__))" pip install -r path/to/requirements.txt python -m pytest --pyargs spacy Calling pytest on the spaCy directory will run only the basic tests. The flag --slow is optional and enables additional tests that take longer. python -m pip install -U pytest # update pytest python -m pytest --pyargs spacy # basic tests python -m pytest --pyargs spacy --slow # basic and slow tests 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. Also see the Discussions FAQ Thread , which is updated more frequently and covers more transitory issues. No compatible package found for [lang] (spaCy vX.X.X). 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 compatibility table 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’s Language class instead, for example from spacy.lang.fr import French . 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 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 also run which python to find out where your Python executable is located. ImportError: No module named 'en_core_web_sm' 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 environment. Run 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. 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 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 spacy to 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 download command. 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 . 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. 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 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 core.autocrlf setting to "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. Changelog Stable Releases Date Version Title 2026-03-29 release-v3.8.14 Bug fix for model downloading in environments without pip on PATH 2026-03-23 release-v3.8.13 Pin confection to new version 2026-03-23 release-v3.8.12 v3.8.12 2025-11-17 release-v3.8.11 Add Windows ARM wheels 2025-11-17 release-v3.8.10 Fix missing Python 3.14 wheels 2025-11-13 release-v3.8.9 Support Python 3.14 2025-11-07 release-v3.8.8 Fix deprecation warnings, update requirements, drop 3.9 2025-05-23 release-v3.8.7 Python 3.13 support, Cython 3, centralize registry entries 2025-05-19 release-v3.8.6 Restore wheels, remove Python 3.13 compatibility 2024-12-11 release-v3.8.3 Improve memory zone stability 2024-10-01 release-v3.8.2 Memory management for persistent services, numpy 2.0 support 2024-06-05 v3.7.5 Download sanitization, Typer compatibility, and a bugfix for linking gold entities 2024-02-15 v3.7.4 New textcat layers and fo/nn language extensions 2023-10-16 v3.7.2 Fixes for APIs and requirements 2023-10-05 v3.7.1 Bug fix for spacy.cli module loading 2023-10-02 v3.7.0 Trained pipelines using Curated Transformers and support for Python 3.12 2023-08-08 v3.6.1 Support for Pydantic v2, find-function CLI and more 2023-07-07 v3.6.0 New span finder component and pipelines for Slovenian 2023-06-28 v3.5.4 Bug fixes for overrides with registered functions and sourced components with listeners 2023-05-25 v3.3.3 Bug fixes for Pydantic and pip 2023-05-25 v3.2.6 Bug fixes for Pydantic and pip 2023-05-15 v3.5.3 Speed improvements, bug fixes and more 2023-04-12 v3.5.2 Pretraining improvements, bug fixes for spans and spancat and more 2023-03-10 v3.5.1 spancat for multi-class labeling, fixes for textcat+transformers and more 2023-01-20 v3.5.0 New CLI commands, language updates, bug fixes and much more 2022-12-16 v3.0.9 Bug fixes and future NumPy compatibility 2022-12-16 v2.3.9 Compatibility with NumPy v1.24+ 2022-12-14 v3.4.4 Bug fixes and future NumPy compatibility Pre-Releases Pre-releases include alpha and beta versions, as well as release candidates. They are not intended for production use. You can download spaCy pre-releases via the spacy-nightly package on pip. prerelease-v3.8.0.dev0 prerelease-v3.7.6a
Markdown	[spaCy](https://spacy.io/) [💥 New: spaCy for PDFs and Word docs](https://github.com/explosion/spacy-layout) - [Usage](https://spacy.io/usage) - [Models](https://spacy.io/models) - [API](https://spacy.io/api) - [Universe](https://spacy.io/universe) Search ```K` # Get started - Get started - [Installation](https://spacy.io/usage) - [Quickstart](https://spacy.io/usage#quickstart) - [Instructions](https://spacy.io/usage#installation) - [Troubleshooting](https://spacy.io/usage#troubleshooting) - [Changelog](https://spacy.io/usage#changelog) - [Models & Languages](https://spacy.io/usage/models) - [Facts & Figures](https://spacy.io/usage/facts-figures) - [spaCy 101](https://spacy.io/usage/spacy-101) - [New in v3.7](https://spacy.io/usage/v3-7) - [New in v3.6](https://spacy.io/usage/v3-6) - [New in v3.5](https://spacy.io/usage/v3-5) - Guides - [Linguistic Features](https://spacy.io/usage/linguistic-features) - [Rule-based Matching](https://spacy.io/usage/rule-based-matching) - [Processing Pipelines](https://spacy.io/usage/processing-pipelines) - [Embeddings & Transformers](https://spacy.io/usage/embeddings-transformers) - [Large Language Models](https://spacy.io/usage/large-language-models) - [Training Models](https://spacy.io/usage/training) - [Layers & Model Architectures](https://spacy.io/usage/layers-architectures) - [spaCy Projects](https://spacy.io/usage/projects) - [Saving & Loading](https://spacy.io/usage/saving-loading) - [Memory Management](https://spacy.io/usage/memory-management) - [Visualizers](https://spacy.io/usage/visualizers) - Resources - [Project Templates](https://github.com/explosion/projects) - [v2.x Documentation](https://v2.spacy.io/) - [Custom Solutions](https://explosion.ai/custom-solutions) # Install spaCy #### 📖 Looking for the old docs? To help you make the transition from v2.x to v3.0, we’ve uploaded the old website to [v2.spacy.io](https://v2.spacy.io/docs). To see what’s changed and how to migrate, see the [v3.0 guide](https://spacy.io/usage/v3). Operating system macOS / OSX Windows Linux Platform x86 ARM / M1 Package manager pip conda from source Hardware CPU GPU Configuration virtual env train models Trained pipelines Catalan Chinese Croatian Danish Dutch English Finnish French German Greek Italian Japanese Korean Lithuanian Macedonian Multi-language Norwegian Bokmål Polish Portuguese Romanian Russian Slovenian Spanish Swedish Ukrainian Select pipeline for efficiency accuracy ``` pip install -U pip setuptools wheelpip install -U spacypython -m spacy download en_core_web_sm ``` ## [Installation instructions](https://spacy.io/usage#installation) spaCy is compatible with 64-bit CPython 3.7+ and runs on Unix/Linux, macOS/OS X and Windows. The latest spaCy releases are available over [pip](https://pypi.python.org/pypi/spacy) and [conda](https://anaconda.org/conda-forge/spacy). ### [pip](https://spacy.io/usage#pip) Using pip, spaCy releases are available as source packages and binary wheels. Before you install spaCy and its dependencies, make sure that your `pip`, `setuptools` and `wheel` are up to date. #### Download pipelines After installation you typically want to download a trained pipeline. For more info and available packages, see the [models directory](https://spacy.io/models). ``` python -m spacy download en_core_web_sm >>> import spacy >>> nlp = spacy.load("en_core_web_sm") ``` ``` pip install -U pip setuptools wheel 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 -U pip setuptools wheel pip install -U spacy ``` spaCy also lets you install extra dependencies by specifying the following keywords in brackets, e.g. `spacy[ja]` or `spacy[lookups,transformers]` (with multiple comma-separated extras). See the `[options.extras_require]` section in spaCy’s [`setup.cfg`](https://github.com/explosion/spaCy/tree/master/setup.cfg) for details on what’s included. #### Example ``` pip install spacy[lookups,transformers] ``` \| Name \| Description \| \|---\|---\| \| `lookups` \| Install [`spacy-lookups-data`](https://github.com/explosion/spacy-lookups-data) for data tables for lemmatization and lexeme normalization. The data is serialized with trained pipelines, so you only need this package if you want to train your own models. \| \| `transformers` \| Install [`spacy-transformers`](https://github.com/explosion/spacy-transformers). The package will be installed automatically when you install a transformer-based pipeline. \| \| `cuda`, … \| Install spaCy with GPU support provided by [CuPy](https://cupy.chainer.org/) for your given CUDA version. See the GPU [installation instructions](https://spacy.io/usage#gpu) for details and options. \| \| `apple` \| Install [`thinc-apple-ops`](https://github.com/explosion/thinc-apple-ops) to improve performance on an Apple M1. \| \| `ja`, `ko`, `th` \| Install additional dependencies required for tokenization for the [languages](https://spacy.io/usage/models#languages). \| ### [conda](https://spacy.io/usage#conda) Thanks to our great community, we’ve been able to re-add conda support. You can also install spaCy via `conda-forge`: ``` conda install -c conda-forge spacy ``` For the feedstock including the build recipe and configuration, check out [this repository](https://github.com/conda-forge/spacy-feedstock). Note that we currently don’t publish any [pre-releases](https://spacy.io/usage#changelog-pre) on conda. ### [Upgrading spaCy](https://spacy.io/usage#upgrading) #### Upgrading from v2 to v3 Although we’ve tried to keep breaking changes to a minimum, upgrading from spaCy v2.x to v3.x may still require some changes to your code base. For details see the sections on [backwards incompatibilities](https://spacy.io/usage/v3#incompat) and [migrating](https://spacy.io/usage/v3#migrating). Also remember to download the new trained pipelines, and retrain your own pipelines. 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`](https://spacy.io/api/cli#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. ``` pip install -U spacy python -m spacy validate ``` ### [Run spaCy with GPU](https://spacy.io/usage#gpu) As of v2.0, spaCy comes with neural network models that are implemented in our machine learning library, [Thinc](https://thinc.ai/). For GPU support, we’ve been grateful to use the work of Chainer’s [CuPy](https://cupy.chainer.org/) module, which provides a numpy-compatible interface for GPU arrays. spaCy can be installed for a CUDA-compatible GPU by specifying `spacy[cuda]`, `spacy[cuda102]`, `spacy[cuda112]`, `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 [`cupy`](https://cupy.chainer.org/). ``` pip install -U spacy[cuda113] ``` Once you have a GPU-enabled installation, the best way to activate it is to call [`spacy.prefer_gpu`](https://spacy.io/api/top-level#spacy.prefer_gpu) or [`spacy.require_gpu()`](https://spacy.io/api/top-level#spacy.require_gpu) somewhere in your script before any pipelines have been loaded. `require_gpu` will raise an error if no GPU is available. ``` import spacy spacy.prefer_gpu() nlp = spacy.load("en_core_web_sm") ``` ### [Compile from source](https://spacy.io/usage#source) The other way to install spaCy is to clone its [GitHub repository](https://github.com/explosion/spaCy) 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](https://pip.pypa.io/en/stable/) and [git](https://git-scm.com/) installed. The compiler part is the trickiest. How to do that depends on your system. See notes on [Ubuntu](https://spacy.io/usage#source-ubuntu), [macOS / OS X](https://spacy.io/usage#source-osx) and [Windows](https://spacy.io/usage#source-windows) for details. ``` python -m pip install -U pip setuptools wheel # install/update build tools git clone https://github.com/explosion/spaCy # clone spaCy cd spaCy # navigate into dir python -m venv .env # create environment in .env source .env/bin/activate # activate virtual env pip install -r requirements.txt # install requirements pip install --no-build-isolation --editable . # compile and install spaCy ``` To install with extras: ``` pip install --no-build-isolation --editable .[lookups,cuda102] ``` How to install compilers and related build tools: - 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](https://developer.apple.com/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](https://visualstudio.microsoft.com/visual-cpp-build-tools/) or [Visual Studio Express](https://www.visualstudio.com/vs/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`. If `numpy` gets downgraded from the most recent release at any point after you’ve compiled `spacy`, you might see an error that looks like this: ``` numpy.ndarray size changed, may indicate binary incompatibility. ``` To fix this, create a new virtual environment and install `spacy` and all of its dependencies using build constraints. [Build constraints](https://pip.pypa.io/en/stable/user_guide/#constraints-files) specify an older version of `numpy` that is only used while compiling `spacy`, 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: ``` PIP_CONSTRAINT=https://raw.githubusercontent.com/explosion/spacy/master/build-constraints.txt \ pip install spacy --no-cache-dir ``` Our build constraints currently specify the oldest supported `numpy` available on PyPI for `x86_64` and `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 [`oldest-supported-numpy`](https://github.com/scipy/oldest-supported-numpy/blob/main/setup.cfg) package to see what the oldest recommended versions of `numpy` are. (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](https://spacy.io/usage#source-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 `.py` files will be reflected as soon as the files are saved, but edits to Cython files (`.pxd`, `.pyx`) will require the `pip install` command 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. ``` pip install -r requirements.txt pip install --no-build-isolation --editable . ``` - Build in parallel. Starting in v3.4.0, you can specify the number of build jobs with the environment variable `SPACY_NUM_BUILD_JOBS`: ``` pip install -r requirements.txt SPACY_NUM_BUILD_JOBS=4 pip install --no-build-isolation --editable . ``` - For editable mode and parallel builds with `python setup.py` instead of `pip` (no longer recommended): ``` pip install -r requirements.txt python setup.py build_ext --inplace -j 4 python setup.py develop ``` #### Visual Studio Code extension ![spaCy extension demo](https://spacy.io/images/spacy-extension-demo.gif) The [spaCy VSCode Extension](https://github.com/explosion/spacy-vscode) 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. 1. Install a supported version of Python on your system (`>=3.7`) 2. Install the [Python Extension for Visual Studio Code](https://code.visualstudio.com/docs/python/python-tutorial) 3. Create a [virtual python environment](https://docs.python.org/3/library/venv.html) 4. Install all python requirements (`spaCy >= 3.4.0` & `pygls >= 1.0.0`) 5. Install [spaCy extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=Explosion.spacy-extension) 6. Select your python environment 7. You are ready to work with `.cfg` files in spaCy\! ### [Building an executable](https://spacy.io/usage#executable) The spaCy repository includes a [`Makefile`](https://github.com/explosion/spaCy/tree/master/Makefile) that builds an executable zip file using [`pex`](https://github.com/pantsbuild/pex) (Python Executable). The executable includes spaCy and all its package dependencies and only requires the system Python at runtime. Building an executable `.pex` file is often the most convenient way to deploy spaCy, as it lets you separate the build from the deployment process. #### Usage To use a `.pex` file, just replace `python` with the path to the file when you execute your code or CLI commands. This is equivalent to running Python in a virtual environment with spaCy installed. ``` ./spacy.pex my_script.py ./spacy.pex -m spacy info ``` ``` git clone https://github.com/explosion/spaCy cd spaCy make ``` You can configure the build process with the following environment variables: \| Variable \| Description \| \|---\|---\| \| `SPACY_EXTRAS` \| Additional Python packages to install alongside spaCy with optional version specifications. Should be a string that can be passed to `pip install`. See [`Makefile`](https://github.com/explosion/spaCy/tree/master/Makefile) for defaults. \| \| `PYVER` \| The Python version to build against. This version needs to be available on your build and runtime machines. Defaults to `3.8`. \| \| `WHEELHOUSE` \| Directory to store the wheel files during compilation. Defaults to `./wheelhouse`. \| ### [Run tests](https://spacy.io/usage#run-tests) spaCy comes with an [extensive test suite](https://github.com/explosion/spaCy/tree/master/spacy/tests). In order to run the tests, you’ll usually want to clone the [repository](https://github.com/explosion/spaCy/tree/master) and [build spaCy from source](https://spacy.io/usage#source). This will also install the required development dependencies and test utilities defined in the `requirements.txt`. 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 [`requirements.txt`](https://github.com/explosion/spaCy/tree/master/requirements.txt): ``` python -c "import os; import spacy; print(os.path.dirname(spacy.__file__))" pip install -r path/to/requirements.txt python -m pytest --pyargs spacy ``` Calling `pytest` on the spaCy directory will run only the basic tests. The flag `--slow` is optional and enables additional tests that take longer. ``` python -m pip install -U pytest # update pytest python -m pytest --pyargs spacy # basic tests python -m pytest --pyargs spacy --slow # basic and slow tests ``` ## [Troubleshooting guide](https://spacy.io/usage#troubleshooting) 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](https://github.com/explosion/spaCy/discussions/8226), which is updated more frequently and covers more transitory issues. #### Help us improve this guide Did you come across a problem like the ones listed here and want to share the solution? You can find the “Suggest edits” button at the bottom of this page that points you to the source. We always appreciate [pull requests](https://github.com/explosion/spaCy/pulls)\! #### No compatible model found ``` No compatible package found for [lang] (spaCy vX.X.X). ``` 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 [compatibility table](https://github.com/explosion/spacy-models/tree/master/compatibility.json) 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](https://spacy.io/usage/models#languages), not all of them come with trained pipelines. To only use the tokenizer, import the language’s `Language` class instead, for example `from spacy.lang.fr import French`. #### Import error: No module named spacy ``` 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 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 also run `which python` to find out where your Python executable is located. #### Import error: No module named \[name\] ``` ImportError: No module named 'en_core_web_sm' ``` 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 environment. Run `pip list` or `pip freeze` to check which pipeline packages you have installed, and install the [correct package](https://spacy.io/models) 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. #### Command not found: spacy ``` 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 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 `spacy` to `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 [`download`](https://spacy.io/api/cli#download) command. #### '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`. #### NER model doesn't recognize other entities anymore after training 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. #### 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 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 [`core.autocrlf`](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) setting to `"false"`, or by committing a [`.gitattributes`](https://git-scm.com/docs/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. ## [Changelog](https://spacy.io/usage#changelog) ### [Stable Releases](https://spacy.io/usage#changelog-stable) \| Date \| Version \| Title \| \|---\|---\|---\| \| 2026-03-29 \| [`release-v3.8.14`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.14) \| Bug fix for model downloading in environments without pip on PATH \| \| 2026-03-23 \| [`release-v3.8.13`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.13) \| Pin confection to new version \| \| 2026-03-23 \| [`release-v3.8.12`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.12) \| v3.8.12 \| \| 2025-11-17 \| [`release-v3.8.11`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.11) \| Add Windows ARM wheels \| \| 2025-11-17 \| [`release-v3.8.10`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.10) \| Fix missing Python 3.14 wheels \| \| 2025-11-13 \| [`release-v3.8.9`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.9) \| Support Python 3.14 \| \| 2025-11-07 \| [`release-v3.8.8`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.8) \| Fix deprecation warnings, update requirements, drop 3.9 \| \| 2025-05-23 \| [`release-v3.8.7`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.7) \| Python 3.13 support, Cython 3, centralize registry entries \| \| 2025-05-19 \| [`release-v3.8.6`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.6) \| Restore wheels, remove Python 3.13 compatibility \| \| 2024-12-11 \| [`release-v3.8.3`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.3) \| Improve memory zone stability \| \| 2024-10-01 \| [`release-v3.8.2`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.2) \| Memory management for persistent services, numpy 2.0 support \| \| 2024-06-05 \| [`v3.7.5`](https://github.com/explosion/spaCy/releases/tag/v3.7.5) \| Download sanitization, Typer compatibility, and a bugfix for linking gold entities \| \| 2024-02-15 \| [`v3.7.4`](https://github.com/explosion/spaCy/releases/tag/v3.7.4) \| New textcat layers and fo/nn language extensions \| \| 2023-10-16 \| [`v3.7.2`](https://github.com/explosion/spaCy/releases/tag/v3.7.2) \| Fixes for APIs and requirements \| \| 2023-10-05 \| [`v3.7.1`](https://github.com/explosion/spaCy/releases/tag/v3.7.1) \| Bug fix for spacy.cli module loading \| \| 2023-10-02 \| [`v3.7.0`](https://github.com/explosion/spaCy/releases/tag/v3.7.0) \| Trained pipelines using Curated Transformers and support for Python 3.12 \| \| 2023-08-08 \| [`v3.6.1`](https://github.com/explosion/spaCy/releases/tag/v3.6.1) \| Support for Pydantic v2, find-function CLI and more \| \| 2023-07-07 \| [`v3.6.0`](https://github.com/explosion/spaCy/releases/tag/v3.6.0) \| New span finder component and pipelines for Slovenian \| \| 2023-06-28 \| [`v3.5.4`](https://github.com/explosion/spaCy/releases/tag/v3.5.4) \| Bug fixes for overrides with registered functions and sourced components with listeners \| \| 2023-05-25 \| [`v3.3.3`](https://github.com/explosion/spaCy/releases/tag/v3.3.3) \| Bug fixes for Pydantic and pip \| \| 2023-05-25 \| [`v3.2.6`](https://github.com/explosion/spaCy/releases/tag/v3.2.6) \| Bug fixes for Pydantic and pip \| \| 2023-05-15 \| [`v3.5.3`](https://github.com/explosion/spaCy/releases/tag/v3.5.3) \| Speed improvements, bug fixes and more \| \| 2023-04-12 \| [`v3.5.2`](https://github.com/explosion/spaCy/releases/tag/v3.5.2) \| Pretraining improvements, bug fixes for spans and spancat and more \| \| 2023-03-10 \| [`v3.5.1`](https://github.com/explosion/spaCy/releases/tag/v3.5.1) \| spancat for multi-class labeling, fixes for textcat+transformers and more \| \| 2023-01-20 \| [`v3.5.0`](https://github.com/explosion/spaCy/releases/tag/v3.5.0) \| New CLI commands, language updates, bug fixes and much more \| \| 2022-12-16 \| [`v3.0.9`](https://github.com/explosion/spaCy/releases/tag/v3.0.9) \| Bug fixes and future NumPy compatibility \| \| 2022-12-16 \| [`v2.3.9`](https://github.com/explosion/spaCy/releases/tag/v2.3.9) \| Compatibility with NumPy v1.24+ \| \| 2022-12-14 \| [`v3.4.4`](https://github.com/explosion/spaCy/releases/tag/v3.4.4) \| Bug fixes and future NumPy compatibility \| ### [Pre-Releases](https://spacy.io/usage#changelog-pre) Pre-releases include alpha and beta versions, as well as release candidates. They are not intended for production use. You can download spaCy pre-releases via the [`spacy-nightly`](https://pypi.org/packages/spacy-nightly) package on pip. [`prerelease-v3.8.0.dev0`](https://github.com/explosion/spaCy/releases/tag/prerelease-v3.8.0.dev0) [`prerelease-v3.7.6a`](https://github.com/explosion/spaCy/releases/tag/prerelease-v3.7.6a) [Suggest edits](https://github.com/explosion/spaCy/tree/master/website/docs/usage/index.mdx) [Read nextModels & Languages](https://spacy.io/usage/models) - spaCy - [Usage](https://spacy.io/usage) - [Models](https://spacy.io/models) - [API Reference](https://spacy.io/api) - [Online Course](https://course.spacy.io/) - [Custom Solutions](https://explosion.ai/custom-solutions) - Community - [Universe](https://spacy.io/universe) - [GitHub Discussions](https://github.com/explosion/spaCy/discussions) - [Issue Tracker](https://github.com/explosion/spaCy/issues) - [Stack Overflow](http://stackoverflow.com/questions/tagged/spacy) - [Merchandise](https://explosion.ai/merch) - Connect - [Bluesky](https://bsky.app/profile/explosion-ai.bsky.social) - [GitHub](https://github.com/explosion/spaCy) - [Live Stream](https://www.youtube.com/playlist?list=PLBmcuObd5An5_iAxNYLJa_xWmNzsYce8c) - [YouTube](https://youtube.com/c/ExplosionAI) - [Blog](https://explosion.ai/blog) - Stay in the loop\! - Receive updates about new releases, tutorials and more. © 2016-2026 [Explosion](https://explosion.ai/) [Legal / Imprint](https://explosion.ai/legal)
Readable Markdown	## Install spaCy Operating system macOS / OSXWindowsLinux Platform x86ARM / M1 Package manager pipcondafrom source Hardware CPUGPU Configuration virtual envtrain models Trained pipelines CatalanChineseCroatianDanishDutchEnglishFinnishFrenchGermanGreekItalianJapaneseKoreanLithuanianMacedonianMulti-languageNorwegian BokmålPolishPortugueseRomanianRussianSlovenianSpanishSwedishUkrainian Select pipeline for efficiencyaccuracy ``` pip install -U pip setuptools wheelpip install -U spacypython -m spacy download en_core_web_sm ``` ## [Installation instructions](https://spacy.io/usage#installation) spaCy is compatible with 64-bit CPython 3.7+ and runs on Unix/Linux, macOS/OS X and Windows. The latest spaCy releases are available over [pip](https://pypi.python.org/pypi/spacy) and [conda](https://anaconda.org/conda-forge/spacy). ### [pip](https://spacy.io/usage#pip) Using pip, spaCy releases are available as source packages and binary wheels. Before you install spaCy and its dependencies, make sure that your `pip`, `setuptools` and `wheel` are up to date. ``` pip install -U pip setuptools wheel 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 -U pip setuptools wheel pip install -U spacy ``` spaCy also lets you install extra dependencies by specifying the following keywords in brackets, e.g. `spacy[ja]` or `spacy[lookups,transformers]` (with multiple comma-separated extras). See the `[options.extras_require]` section in spaCy’s [`setup.cfg`](https://github.com/explosion/spaCy/tree/master/setup.cfg) for details on what’s included. \| Name \| Description \| \|---\|---\| \| `lookups` \| Install [`spacy-lookups-data`](https://github.com/explosion/spacy-lookups-data) for data tables for lemmatization and lexeme normalization. The data is serialized with trained pipelines, so you only need this package if you want to train your own models. \| \| `transformers` \| Install [`spacy-transformers`](https://github.com/explosion/spacy-transformers). The package will be installed automatically when you install a transformer-based pipeline. \| \| `cuda`, … \| Install spaCy with GPU support provided by [CuPy](https://cupy.chainer.org/) for your given CUDA version. See the GPU [installation instructions](https://spacy.io/usage#gpu) for details and options. \| \| `apple` \| Install [`thinc-apple-ops`](https://github.com/explosion/thinc-apple-ops) to improve performance on an Apple M1. \| \| `ja`, `ko`, `th` \| Install additional dependencies required for tokenization for the [languages](https://spacy.io/usage/models#languages). \| ### [conda](https://spacy.io/usage#conda) Thanks to our great community, we’ve been able to re-add conda support. You can also install spaCy via `conda-forge`: ``` conda install -c conda-forge spacy ``` For the feedstock including the build recipe and configuration, check out [this repository](https://github.com/conda-forge/spacy-feedstock). Note that we currently don’t publish any [pre-releases](https://spacy.io/usage#changelog-pre) on conda. ### [Upgrading spaCy](https://spacy.io/usage#upgrading) 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`](https://spacy.io/api/cli#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. ``` pip install -U spacy python -m spacy validate ``` ### [Run spaCy with GPU](https://spacy.io/usage#gpu) As of v2.0, spaCy comes with neural network models that are implemented in our machine learning library, [Thinc](https://thinc.ai/). For GPU support, we’ve been grateful to use the work of Chainer’s [CuPy](https://cupy.chainer.org/) module, which provides a numpy-compatible interface for GPU arrays. spaCy can be installed for a CUDA-compatible GPU by specifying `spacy[cuda]`, `spacy[cuda102]`, `spacy[cuda112]`, `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 [`cupy`](https://cupy.chainer.org/). ``` pip install -U spacy[cuda113] ``` Once you have a GPU-enabled installation, the best way to activate it is to call [`spacy.prefer_gpu`](https://spacy.io/api/top-level#spacy.prefer_gpu) or [`spacy.require_gpu()`](https://spacy.io/api/top-level#spacy.require_gpu) somewhere in your script before any pipelines have been loaded. `require_gpu` will raise an error if no GPU is available. ``` import spacy spacy.prefer_gpu() nlp = spacy.load("en_core_web_sm") ``` ### [Compile from source](https://spacy.io/usage#source) The other way to install spaCy is to clone its [GitHub repository](https://github.com/explosion/spaCy) 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](https://pip.pypa.io/en/stable/) and [git](https://git-scm.com/) installed. The compiler part is the trickiest. How to do that depends on your system. See notes on [Ubuntu](https://spacy.io/usage#source-ubuntu), [macOS / OS X](https://spacy.io/usage#source-osx) and [Windows](https://spacy.io/usage#source-windows) for details. ``` python -m pip install -U pip setuptools wheel # install/update build tools git clone https://github.com/explosion/spaCy # clone spaCy cd spaCy # navigate into dir python -m venv .env # create environment in .env source .env/bin/activate # activate virtual env pip install -r requirements.txt # install requirements pip install --no-build-isolation --editable . # compile and install spaCy ``` To install with extras: ``` pip install --no-build-isolation --editable .[lookups,cuda102] ``` How to install compilers and related build tools: - 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](https://developer.apple.com/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](https://visualstudio.microsoft.com/visual-cpp-build-tools/) or [Visual Studio Express](https://www.visualstudio.com/vs/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`. If `numpy` gets downgraded from the most recent release at any point after you’ve compiled `spacy`, you might see an error that looks like this: ``` numpy.ndarray size changed, may indicate binary incompatibility. ``` To fix this, create a new virtual environment and install `spacy` and all of its dependencies using build constraints. [Build constraints](https://pip.pypa.io/en/stable/user_guide/#constraints-files) specify an older version of `numpy` that is only used while compiling `spacy`, 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: ``` PIP_CONSTRAINT=https://raw.githubusercontent.com/explosion/spacy/master/build-constraints.txt \ pip install spacy --no-cache-dir ``` Our build constraints currently specify the oldest supported `numpy` available on PyPI for `x86_64` and `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 [`oldest-supported-numpy`](https://github.com/scipy/oldest-supported-numpy/blob/main/setup.cfg) package to see what the oldest recommended versions of `numpy` are. (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](https://spacy.io/usage#source-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 `.py` files will be reflected as soon as the files are saved, but edits to Cython files (`.pxd`, `.pyx`) will require the `pip install` command 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. ``` pip install -r requirements.txt pip install --no-build-isolation --editable . ``` - Build in parallel. Starting in v3.4.0, you can specify the number of build jobs with the environment variable `SPACY_NUM_BUILD_JOBS`: ``` pip install -r requirements.txt SPACY_NUM_BUILD_JOBS=4 pip install --no-build-isolation --editable . ``` - For editable mode and parallel builds with `python setup.py` instead of `pip` (no longer recommended): ``` pip install -r requirements.txt python setup.py build_ext --inplace -j 4 python setup.py develop ``` #### Visual Studio Code extension ![spaCy extension demo](https://spacy.io/images/spacy-extension-demo.gif) The [spaCy VSCode Extension](https://github.com/explosion/spacy-vscode) 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. 1. Install a supported version of Python on your system (`>=3.7`) 2. Install the [Python Extension for Visual Studio Code](https://code.visualstudio.com/docs/python/python-tutorial) 3. Create a [virtual python environment](https://docs.python.org/3/library/venv.html) 4. Install all python requirements (`spaCy >= 3.4.0` & `pygls >= 1.0.0`) 5. Install [spaCy extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=Explosion.spacy-extension) 6. Select your python environment 7. You are ready to work with `.cfg` files in spaCy\! ### [Building an executable](https://spacy.io/usage#executable) The spaCy repository includes a [`Makefile`](https://github.com/explosion/spaCy/tree/master/Makefile) that builds an executable zip file using [`pex`](https://github.com/pantsbuild/pex) (Python Executable). The executable includes spaCy and all its package dependencies and only requires the system Python at runtime. Building an executable `.pex` file is often the most convenient way to deploy spaCy, as it lets you separate the build from the deployment process. ``` git clone https://github.com/explosion/spaCy cd spaCy make ``` You can configure the build process with the following environment variables: \| Variable \| Description \| \|---\|---\| \| `SPACY_EXTRAS` \| Additional Python packages to install alongside spaCy with optional version specifications. Should be a string that can be passed to `pip install`. See [`Makefile`](https://github.com/explosion/spaCy/tree/master/Makefile) for defaults. \| \| `PYVER` \| The Python version to build against. This version needs to be available on your build and runtime machines. Defaults to `3.8`. \| \| `WHEELHOUSE` \| Directory to store the wheel files during compilation. Defaults to `./wheelhouse`. \| ### [Run tests](https://spacy.io/usage#run-tests) spaCy comes with an [extensive test suite](https://github.com/explosion/spaCy/tree/master/spacy/tests). In order to run the tests, you’ll usually want to clone the [repository](https://github.com/explosion/spaCy/tree/master) and [build spaCy from source](https://spacy.io/usage#source). This will also install the required development dependencies and test utilities defined in the `requirements.txt`. 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 [`requirements.txt`](https://github.com/explosion/spaCy/tree/master/requirements.txt): ``` python -c "import os; import spacy; print(os.path.dirname(spacy.__file__))" pip install -r path/to/requirements.txt python -m pytest --pyargs spacy ``` Calling `pytest` on the spaCy directory will run only the basic tests. The flag `--slow` is optional and enables additional tests that take longer. ``` python -m pip install -U pytest # update pytest python -m pytest --pyargs spacy # basic tests python -m pytest --pyargs spacy --slow # basic and slow tests ``` ## [Troubleshooting guide](https://spacy.io/usage#troubleshooting) 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](https://github.com/explosion/spaCy/discussions/8226), which is updated more frequently and covers more transitory issues. #### ``` No compatible package found for [lang] (spaCy vX.X.X). ``` 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 [compatibility table](https://github.com/explosion/spacy-models/tree/master/compatibility.json) 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](https://spacy.io/usage/models#languages), not all of them come with trained pipelines. To only use the tokenizer, import the language’s `Language` class instead, for example `from spacy.lang.fr import French`. #### ``` 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 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 also run `which python` to find out where your Python executable is located. #### ``` ImportError: No module named 'en_core_web_sm' ``` 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 environment. Run `pip list` or `pip freeze` to check which pipeline packages you have installed, and install the [correct package](https://spacy.io/models) 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. #### ``` 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 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 `spacy` to `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 [`download`](https://spacy.io/api/cli#download) command. #### ``` 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`. #### 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. #### ``` 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 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 [`core.autocrlf`](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) setting to `"false"`, or by committing a [`.gitattributes`](https://git-scm.com/docs/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. ## [Changelog](https://spacy.io/usage#changelog) ### [Stable Releases](https://spacy.io/usage#changelog-stable) \| Date \| Version \| Title \| \|---\|---\|---\| \| 2026-03-29 \| [`release-v3.8.14`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.14) \| Bug fix for model downloading in environments without pip on PATH \| \| 2026-03-23 \| [`release-v3.8.13`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.13) \| Pin confection to new version \| \| 2026-03-23 \| [`release-v3.8.12`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.12) \| v3.8.12 \| \| 2025-11-17 \| [`release-v3.8.11`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.11) \| Add Windows ARM wheels \| \| 2025-11-17 \| [`release-v3.8.10`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.10) \| Fix missing Python 3.14 wheels \| \| 2025-11-13 \| [`release-v3.8.9`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.9) \| Support Python 3.14 \| \| 2025-11-07 \| [`release-v3.8.8`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.8) \| Fix deprecation warnings, update requirements, drop 3.9 \| \| 2025-05-23 \| [`release-v3.8.7`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.7) \| Python 3.13 support, Cython 3, centralize registry entries \| \| 2025-05-19 \| [`release-v3.8.6`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.6) \| Restore wheels, remove Python 3.13 compatibility \| \| 2024-12-11 \| [`release-v3.8.3`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.3) \| Improve memory zone stability \| \| 2024-10-01 \| [`release-v3.8.2`](https://github.com/explosion/spaCy/releases/tag/release-v3.8.2) \| Memory management for persistent services, numpy 2.0 support \| \| 2024-06-05 \| [`v3.7.5`](https://github.com/explosion/spaCy/releases/tag/v3.7.5) \| Download sanitization, Typer compatibility, and a bugfix for linking gold entities \| \| 2024-02-15 \| [`v3.7.4`](https://github.com/explosion/spaCy/releases/tag/v3.7.4) \| New textcat layers and fo/nn language extensions \| \| 2023-10-16 \| [`v3.7.2`](https://github.com/explosion/spaCy/releases/tag/v3.7.2) \| Fixes for APIs and requirements \| \| 2023-10-05 \| [`v3.7.1`](https://github.com/explosion/spaCy/releases/tag/v3.7.1) \| Bug fix for spacy.cli module loading \| \| 2023-10-02 \| [`v3.7.0`](https://github.com/explosion/spaCy/releases/tag/v3.7.0) \| Trained pipelines using Curated Transformers and support for Python 3.12 \| \| 2023-08-08 \| [`v3.6.1`](https://github.com/explosion/spaCy/releases/tag/v3.6.1) \| Support for Pydantic v2, find-function CLI and more \| \| 2023-07-07 \| [`v3.6.0`](https://github.com/explosion/spaCy/releases/tag/v3.6.0) \| New span finder component and pipelines for Slovenian \| \| 2023-06-28 \| [`v3.5.4`](https://github.com/explosion/spaCy/releases/tag/v3.5.4) \| Bug fixes for overrides with registered functions and sourced components with listeners \| \| 2023-05-25 \| [`v3.3.3`](https://github.com/explosion/spaCy/releases/tag/v3.3.3) \| Bug fixes for Pydantic and pip \| \| 2023-05-25 \| [`v3.2.6`](https://github.com/explosion/spaCy/releases/tag/v3.2.6) \| Bug fixes for Pydantic and pip \| \| 2023-05-15 \| [`v3.5.3`](https://github.com/explosion/spaCy/releases/tag/v3.5.3) \| Speed improvements, bug fixes and more \| \| 2023-04-12 \| [`v3.5.2`](https://github.com/explosion/spaCy/releases/tag/v3.5.2) \| Pretraining improvements, bug fixes for spans and spancat and more \| \| 2023-03-10 \| [`v3.5.1`](https://github.com/explosion/spaCy/releases/tag/v3.5.1) \| spancat for multi-class labeling, fixes for textcat+transformers and more \| \| 2023-01-20 \| [`v3.5.0`](https://github.com/explosion/spaCy/releases/tag/v3.5.0) \| New CLI commands, language updates, bug fixes and much more \| \| 2022-12-16 \| [`v3.0.9`](https://github.com/explosion/spaCy/releases/tag/v3.0.9) \| Bug fixes and future NumPy compatibility \| \| 2022-12-16 \| [`v2.3.9`](https://github.com/explosion/spaCy/releases/tag/v2.3.9) \| Compatibility with NumPy v1.24+ \| \| 2022-12-14 \| [`v3.4.4`](https://github.com/explosion/spaCy/releases/tag/v3.4.4) \| Bug fixes and future NumPy compatibility \| ### [Pre-Releases](https://spacy.io/usage#changelog-pre) Pre-releases include alpha and beta versions, as well as release candidates. They are not intended for production use. You can download spaCy pre-releases via the [`spacy-nightly`](https://pypi.org/packages/spacy-nightly) package on pip. [`prerelease-v3.8.0.dev0`](https://github.com/explosion/spaCy/releases/tag/prerelease-v3.8.0.dev0) [`prerelease-v3.7.6a`](https://github.com/explosion/spaCy/releases/tag/prerelease-v3.7.6a)
Shard	119 (laksa)
Root Hash	6839834103567801919
Unparsed URL	io,spacy!/usage s443