What causes "Install "spacy" requirements | pip install -U g4f[files]" in xtekky/gpt4free?

pip install -U 'g4f[files]' then pip install spacy.

xtekky/gpt4free · warning · MissingRequirementsError

Install "spacy" requirements | pip install -U g4f[files]

Error message

Install "spacy" requirements | pip install -U g4f[files]

What it means

spacy_refine_chunks raises MissingRequirementsError immediately when spacy is not installed. This helper refines document chunks using an NLP model, so it requires the 'spacy' optional dependency plus the 'en_core_web_sm' model (which must be downloaded separately via python -m spacy download).

Source

Thrown at g4f/tools/files.py:162

        if not has_beautifulsoup4:
            raise MissingRequirementsError(
                f'Install "beautifulsoup4" requirements | pip install -U g4f[files]'
            )
        return True
    elif filename.endswith(".zip"):
        return True
    elif filename.endswith("package-lock.json") and filename != FILE_LIST:
        return False
    else:
        extension = os.path.splitext(filename)[1][1:]
        if extension in PLAIN_FILE_EXTENSIONS:
            return True
    return False


def spacy_refine_chunks(source_iterator):
    if not has_spacy:
        raise MissingRequirementsError(
            f'Install "spacy" requirements | pip install -U g4f[files]'
        )

    nlp = spacy.load("en_core_web_sm")
    for page in source_iterator:
        doc = nlp(page)
        # for chunk in doc.noun_chunks:
        #    yield " ".join([token.lemma_ for token in chunk if not token.is_stop])
        # for token in doc:
        #     if not token.is_space:
        #         yield token.lemma_.lower()
        #         yield " "
        sentences = list(doc.sents)
        summary = sorted(sentences, key=lambda x: len(x.text), reverse=True)[:2]
        for sent in summary:
            yield sent.text

View on GitHub (pinned to 973504e177)

Solutions

pip install -U 'g4f[files]' then pip install spacy.
Download the required model: python -m spacy download en_core_web_sm.
Verify: python -c "import spacy; spacy.load('en_core_web_sm')".
Or skip spacy_refine_chunks and consume the source iterator directly (plain chunking works without spacy).

Example fix

# before
from g4f.tools.files import spacy_refine_chunks
chunks = spacy_refine_chunks(pages)  # MissingRequirementsError

# after
# shell: pip install spacy && python -m spacy download en_core_web_sm
chunks = spacy_refine_chunks(pages)

Defensive patterns

Strategy: validation

Validate before calling

def spacy_ready() -> bool:
    try:
        import spacy
        spacy.util.get_installed_models()  # cheap check
        return 'en_core_web_sm' in spacy.util.get_installed_models()
    except ImportError:
        return False

if not spacy_ready():
    raise SystemExit('Run: pip install spacy && python -m spacy download en_core_web_sm')

Type guard

from g4f.errors import MissingRequirementsError

def can_refine_chunks() -> bool:
    try:
        import spacy  # noqa
        return True
    except ImportError:
        return False

Try / catch

from g4f.errors import MissingRequirementsError
from g4f.tools.files import spacy_refine_chunks
try:
    refined = list(spacy_refine_chunks(pages))
except MissingRequirementsError:
    refined = pages  # degrade gracefully to raw chunks

Prevention

Install spacy AND download en_core_web_sm — the model is a separate step
Guard spacy_refine_chunks with an import check and fall back to raw chunks
Smoke-test model loading at app start
Document the extra deps for any feature using chunk refinement

When it happens

Trigger: Calling g4f.tools.files.spacy_refine_chunks (or a code path that uses it for chunk refinement in file/RAG processing) without spacy in the environment. Note: even after installing spacy, spacy.load('en_core_web_sm') will raise OSError if the model wasn't downloaded.

Common situations: Using the files extra without the spacy extra; new machine without the downloaded language model; docs/samples that call the chunk refiner without stating its deps.

Related errors

AI-assisted analysis of xtekky/gpt4free@973504e177 (2026-08-14). Data as JSON: /api/errors/c638e9d71826261f. Report an issue: GitHub.