python config_error ai_generated true

error: Multiple top-level packages discovered in a flat-layout: ['src', 'tests', 'docs'].

ID: python/setuptools-package-discovery-flat-layout

Also available as: JSON · Markdown · 中文
80%Fix Rate
88%Confidence
0Evidence
2024-02-27First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
3.x active — — —

Root Cause

setuptools auto-discovery refuses to guess which top-level directory is the real package when several sibling directories look like packages; explicit configuration is required.

generic

中文

当多个同级目录看起来像包时，setuptools 自动发现拒绝猜测哪个顶级目录是真正的包；需要显式配置。

Workarounds

  1. 97% success 
    [tool.setuptools.packages.find]
where = ["src"]
include = ["mypkg*"]
# or list them
[tool.setuptools]
packages = ["mypkg"]
  2. 94% success 
    mkdir -p src/mypkg
mv mypkg/* src/mypkg/
touch src/mypkg/__init__.py
# then configure
[tool.setuptools.packages.find]
where = ["src"]

Dead Ends

Common approaches that don't work:

  1. 60% fail

    Works around the symptom but breaks conventional tooling and CI that expect those names.

  2. 80% fail

    Makes the ambiguity worse; setuptools now sees even more candidate packages.