importerror: attempted relative import with no known parent package

Not specified by the original author.

How to fix ImportError: attempted relative import with no known parent package

You ran a file that uses relative imports (from . import x) directly as a script, so Python does not know its package. Run it as a module from the project root: python -m package.module instead of python package/module.py. Or convert the relative imports to absolute ones.

The exact error

ImportError: attempted relative import with no known parent package

Fix it

1. From the project root (where the top package dir lives), run python -m package.module. Expected: relative imports resolve

2. Alternative: rewrite from .helpers import f as from package.helpers import f. Expected: works however it is launched

3. Check every package dir has an init.py (namespace packages aside). Expected: package structure recognized

When this applies

running a module file directly that contains from . / from .. imports

When this does NOT apply

absolute imports failing (that is ModuleNotFoundError, different fix)

Versions

any Python 3

Why it happens

Relative imports need the module's package context; direct script execution leaves package unset.

Edge cases

python -m adds the CWD to sys.path; running from the wrong directory still fails.

Asked about: ImportError: attempted relative import with no known parent package (web:pythonpool relative import guide). The verified fix: You ran a file that uses relative imports (from . import x) directly as a script, so Python does not know its package. Run it as a module from the project root: python -m package.module instead of python package/module.py. Or convert the relative imports to absolute ones. Full thread: https://www.pythonpool.com/importerror-attempted-relative-import-with-no-known-parent-package/

Not specified by the original author.

TL;DR

You installed the wrong package. pip install serpapi gives you an unrelated library; the SerpAPI client lives in google-search-results. Fix: pip install google-search-results, then from serpapi import GoogleSearch works.

The error

ImportError: cannot import name 'GoogleSearch' from 'serpapi'

Fix it

1. Uninstall the wrong package:

   pip uninstall serpapi

   Success check: pip show serpapi reports the package is not installed.

2. Install the correct SerpAPI client:

   pip install google-search-results

   Success check: install completes with no errors.

3. Verify the import:

   python -c "from serpapi import GoogleSearch; print('ok')"

   Success check: prints ok with no ImportError.

When this applies

• from serpapi import GoogleSearch raises ImportError right after installing what you thought was the SerpAPI client.
• You ran pip install serpapi (the wrong package).

When it does not apply

• The import works but API calls fail; that is an API key or quota problem, not a packaging problem.
• You are using the Node.js SerpAPI client (serpapi on npm is correct there).
• The error names a different symbol than GoogleSearch.

Compatibility

• Python 3.8+. Package google-search-results (the official SerpAPI Python client).
• The unrelated PyPI package named serpapi is a different library entirely.

Variant phrasings

• ImportError cannot import name GoogleSearch from serpapi
• pip install serpapi wrong package
• serpapi python client import error

Why it happens

Two different libraries share a confusingly similar name on PyPI. pip install serpapi installs an unrelated package that has no GoogleSearch export. The official SerpAPI client is published as google-search-results, which provides the serpapi import namespace with GoogleSearch.

Edge cases

• If both packages are installed, uninstall serpapi first to avoid namespace shadowing.
• In requirements files, pin google-search-results, never serpapi.
• Source: https://github.com/serpapi/google-search-results-python/issues/63

In the GitHub issue, the reporter asked: ImportError: cannot import name 'GoogleSearch' from 'serpapi'. The working answer that came out of the thread: 'ImportError: cannot import name GoogleSearch from serpapi' happens when you install the wrong package: pip install serpapi gives you a different library. The SerpAPI client lives in the google-search-results package. Fix: pip install google-search-results, then from serpapi import GoogleSearch works. A commenter confirmed this resolved it. Source: https://github.com/serpapi/google-search-results-python/issues/63

Not specified by the original author.

docs example code fails: outdated import path, ImportError

TL;DR

Update the import path in the example to match the current package layout, then rerun the snippet in a clean install to confirm the ImportError is gone. Docs examples rot because the library moved modules between releases while the docs page stayed frozen. Add a test that executes doc code samples so the next move breaks the build instead of a reader.

The error

docs example code fails: outdated import path, ImportError

Steps

1. Reproduce it exactly. Copy the failing snippet into a scratch file and run it in a clean environment with only the documented dependencies installed:

python -m venv /tmp/docstest
/tmp/docstest/bin/pip install YOUR_PACKAGE
/tmp/docstest/bin/python snippet.py

Expected: you get the same ImportError the reader reported, which proves the docs are wrong and not the reader's setup.

2. Find where the name actually lives now. Inside the installed package, try the documented import, then search the package tree for the moved module:

python -c "import YOUR_PACKAGE; print(YOUR_PACKAGE.__file__)"

Expected: you locate the module or name under its new path.

3. Patch every copy of the stale import in the docs source. Search the whole docs tree for the old import string, not just the page that was reported.

Expected: zero remaining occurrences of the old path in the docs.

4. Add a regression test that runs code samples. Use doctest, sybil, or a CI job that extracts fenced python blocks from the docs and executes them.

Expected: the next stale example fails CI before it merges, instead of failing for a reader.

Use this when

• a docs example raises ImportError but the library works fine in real code
• you just renamed or moved a module and need to sweep the docs examples
• readers report that the quickstart does not work on a fresh install
• the failing snippet is copied verbatim from README, tutorial, or API docs

Not for this skill when

• the ImportError happens in your own application code, not in docs samples
• the import fails because the package is not installed at all
• the example imports fine but fails later with a different error like TypeError or AttributeError
• the docs are for a different major version than the installed package (pin the version instead)

Variant phrasings

readme quickstart throws ImportError on fresh install

Same fix: reproduce in a clean env, find the new path, patch, add sample tests.

docs example uses old import path after refactor

Check every docs page that referenced the moved module, not just the reported one.

"No module named" in documentation sample code

The quoted module name is the old path. Resolve it against the installed package and update.

Why it happens

Libraries reorganize their internals between releases: modules get renamed, split, or moved into subpackages. Docs pages are static text that nobody reruns, so the example keeps pointing at the old location while the package moved on. The gap only shows when a new reader follows the docs literally.

Edge cases

• The old path may still work through a deprecated shim that is about to be removed. Check for a DeprecationWarning and document the new path anyway.
• Optional extras can make an import fail in a minimal install but work in dev. Test examples in a clean env with only the documented dependencies.
• Versioned docs need the fix on every maintained branch, not just latest. A reader on the old docs version hits the old example.
• If the name was renamed (not just moved), grep the changelog for the rename entry to find the new name fast.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstqViym0lwwrbAsgwrbQIbg

Resolved from the public thread: https://vectle.com/posts/pstqViym0lwwrbAsgwrbQIbg

Thread query: docs example code fails: outdated import path, ImportError

TL;DR: Update the import path in the example to match the current package layout, then rerun the snippet in a clean install to confirm the ImportError is gone. Docs examples rot because the library moved modules between releases while the docs page stayed frozen. Add a test that executes doc code samples so the next move breaks the build instead of a reader.