Advanced

spaCy Best Practices

Production deployment strategies, custom pipeline components, performance optimization, and scaling tips for spaCy applications.

Performance Optimization

Python - Speed up processing

import spacy

# 1. Disable unused components
nlp = spacy.load("en_core_web_sm", disable=["parser", "lemmatizer"])

# 2. Use nlp.pipe() for batch processing (much faster than looping)
texts = ["First document.", "Second document.", "Third document."]
docs = list(nlp.pipe(texts, batch_size=50))

# 3. Use n_process for multiprocessing
docs = list(nlp.pipe(texts, n_process=4, batch_size=100))

# 4. Disable components temporarily
with nlp.select_pipes(enable=["ner"]):
    doc = nlp("Process only NER for this text")

Custom Pipeline Components

Python - Create a custom component

from spacy.language import Language
from spacy.tokens import Doc, Span

# Register a custom component
@Language.component("word_counter")
def word_counter(doc):
    """Add word count as a custom attribute."""
    doc._.word_count = len([t for t in doc if not t.is_punct])
    return doc

# Register custom attribute
Doc.set_extension("word_count", default=0, force=True)

# Add to pipeline
nlp.add_pipe("word_counter", last=True)

doc = nlp("spaCy makes NLP easy and fast!")
print(f"Word count: {doc._.word_count}")  # 6

Production Deployment

Strategy	Recommendation
Model packaging	Use `spacy package` to create installable Python packages from trained models.
API serving	Wrap with FastAPI or Flask. Load the model once at startup, not per request.
Docker	Install model in Dockerfile with `pip install ./model.tar.gz`. Keep images small.
Memory	Use `nlp.max_length` to limit document size. Monitor RSS memory in production.
Versioning	Version models with their training data. Use W&B or MLflow for experiment tracking.

Python - FastAPI deployment

from fastapi import FastAPI
import spacy

app = FastAPI()
nlp = spacy.load("en_core_web_sm")  # Load once at startup

@app.post("/analyze")
async def analyze(text: str):
    doc = nlp(text)
    return {
        "entities": [{"text": e.text, "label": e.label_} for e in doc.ents],
        "tokens": len(doc),
        "sentences": len(list(doc.sents)),
    }

Common Pitfalls

⚠

Loading model per request: spacy.load() is expensive. Load once and reuse the nlp object.
Not using nlp.pipe(): Processing documents one at a time is much slower than batching with nlp.pipe().
Forgetting to disable components: If you only need tokenization, disable everything else for 3-5x speedup.
Model size mismatch: Don't use en_core_web_trf (transformer) when en_core_web_sm is sufficient. Save resources.
Not setting max_length: Very long documents can cause memory issues. Set nlp.max_length = 2000000.

Frequently Asked Questions

Yes! The spacy-transformers package lets you use any Hugging Face model as a spaCy pipeline component. Install it with pip install spacy-transformers and use the en_core_web_trf model or configure custom transformer models.

spaCy supports 75+ languages. Load language-specific models like de_core_news_sm (German) or zh_core_web_sm (Chinese). For multilingual applications, use the xx_ent_wiki_sm model or load multiple language models.

spaCy v3 introduced config-driven training, transformer support, project workflows, and a new training CLI. If you're starting new, always use v3. Migration from v2 requires updating training scripts and some API changes.