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.

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.

Not specified by the original author.

TL;DR

The confirmed workaround was downgrading python-protobuf to 5.29.3, and the distro bug was later fixed upstream.

Steps

1. Issue googleapis/google-cloud-python#15023 (closed, 15 comments): We haven't recently started to see import issues with packages that use google-api-core in openSUSE Tumbleweed.
2. For example, the package celery fails to import google.cloud [1]:
3. `

[ 21s] ==================================== ERRORS ==================================== [ 21s] ________________ ERROR collecting t/unit/backends/testgcs.py _________________ [ 21s] ImportError while importing test module '[HOME]/...'. [ 21s] Hint: make sure your test modules/packages have valid Python...

4. The breakage on openSUSE came from the distro's python-protobuf package, not from Google Cloud libraries themselves. The confirmed workaround was downgrading python-protobuf to 5.29.3, and the distro bug was later fixed upstream. So: if you hit protobuf import or version errors on openSUSE, update the distro package (or pin python-protobuf to 5.29.3 as a stopgap); no change to your Google Cloud client code is needed.

When to use

You are seeing this: For example, the package celery fails to import google.cloud [1]: ``` [ 21s] ==================================== ERRORS ==================================== [ 21s] ________________ ERROR collecting t/unit/backends/testgcs.py _________________ [ 21s]... Use this skill when you run into "Failing imports for submodules of the google-api-core packages".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: 5.29.3. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

In gh:googleapis/google-cloud-python#15023 (Google Cloud), the issue reported was: Issue googleapis/google-cloud-python#15023 (closed, 15 comments): We haven't recently started to see import issues with packages that use google-api-core in openSUSE Tumbleweed.

For example, the package celery fails to import google.cloud [1]:

[   21s] ==================================== ERRORS ====================================
[   21s] _________________ ERROR collecting t/unit/backends/test_gcs.py _________________
[   21s] ImportError while importing test module '[HOME]/...'.
[   21s] Hint: make sure your test modules/packages have valid Python... The verified resolution from the thread: The breakage on openSUSE came from the distro's `python-protobuf` package, not from Google Cloud libraries themselves. The confirmed workaround was downgrading `python-protobuf` to 5.29.3, and the distro bug was later fixed upstream. So: if you hit protobuf import or version errors on openSUSE, update the distro package (or pin python-protobuf to 5.29.3 as a stopgap); no change to your Google Cloud client code is needed. Source: mount the host path https at container path //github.com/googleapis/google-cloud-python/issues/15023