Editable mode : import error outside project dir

[wilgri]

I don't manage to make the editable mode pip install -e . work for a local installation of my project. After the installation, when I import a constructor from a module of my package within in python shell instance running outside my project directory, I got an import error. Here is reproducible example to understand my problem.

What am I missing ?

note : without the editable mode, everything works

Example

setuptools_test/
__| pyproject.toml
__| setuptools_test/
______| __init__.py
______| base.py
_______ module/
__________| __init__.py
__________| base.py

setuptools_test/pyproject.toml

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "setuptools_test"
version = "0.0.1"
dependencies = [
    "requests",
    'importlib-metadata; python_version>="3.11"',
]

setuptools_test/setuptools_test/__init__.py

from .base import FirstClass

setuptools_test/setuptools_test/base.py

class FirstClass: ...

setuptools_test/setuptools_test/module/__init__.py

from .base import SecondClass

setuptools_test/setuptools_test/module/base.py

from setuptools_test import FirstClass

class SecondClass(FirstClass): ...

Problem Then, in setuptools_test/, after running python -m pip install -e ., outside setuptools_test/, I got :

>>> from setuptools_test.module import SecondClass
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File ".../setuptools_test/setuptools_test/module/__init__.py", line 1, in <module>
    from .base import SecondClass
  File ".../setuptools_test/setuptools_test/module/base.py", line 1, in <module>
    from setuptools_test import FirstClass
ImportError: cannot import name 'FirstClass' from 'setuptools_test' (unknown location)

But, without the editable mode, it works.

Versions installed

ubuntu 22.04.4, python 3.11 installed with apt
pip 25.2

version from `python -m pip freeze --all``

autocommand==2.2.2
backports.tarfile==1.2.0
build==1.3.0
certifi==2025.8.3
charset-normalizer==3.4.3
idna==3.10
importlib_metadata==8.7.0
jaraco.context==6.0.1
jaraco.functools==4.3.0
jaraco.text==4.0.0
more-itertools==10.7.0
packaging==25.0
pip==22.0.2
platformdirs==4.4.0
pyproject_hooks==1.2.0
requests==2.32.5
setuptools==80.9.0
setuptools_test @ file:///.../setuptools_test
urllib3==2.5.0
wheel==0.45.1
zipp==3.23.0
``

[ShreeChaturvedi]

Your project folder and package share the name setuptools_test. When Python runs with the parent of that folder as cwd, that empty path entry wins, so setuptools_test is the project folder (no __init__.py). It is a namespace package with no FirstClass. Editable still reaches the real submodules, which is why you see cannot import name 'FirstClass' from 'setuptools_test' (unknown location).

Quick check:

import setuptools_test
print(setuptools_test, getattr(setuptools_test, "__file__", None))

(namespace) and None means the folder is shadowing the install.

Pick one fix:

1. Import the class from its module:

from setuptools_test.base import FirstClass
# or: from ..base import FirstClass

2. Use src-layout so the project root is not importable as the package:

setuptools_test/
  pyproject.toml
  src/setuptools_test/...

3. Or install strict editable:

pip install -e . --config-settings editable_mode=strict

Pitfall: with a flat layout, avoid running Python with cwd set to the parent of the project folder.