[FR] `package-dir`-aware `find:` directive

[xdewx]

setuptools version

setuptools>=80.0

Python version

3.13

OS

windows

Additional environment information

No response

Description

[project]

# 需要更改发布到pypi的包名时改这里
name = "pyproject-tmpl"
dynamic = ["version"]
description = "template python project with necessary configurations"
readme = "README.md"
requires-python = ">=3.10"

dependencies = [
    "alembic>=1.17.2",
    "ipa-python-kit>=0.0.7",
    "sqlmodel>=0.0.31",
    "typer>=0.20.0",
    "typing-extensions>=4.15.0",
]

[project.optional-dependencies]
system = [
    "psutil>=7.2.1",
]

all =[
    "pyproject-tmpl[system]"
]
# 使用uv_build时
# [build-system]
# requires = ["uv_build>=0.7.4,<0.8.0"]
# build-backend = "uv_build"

# [tool.uv.build-backend]
# module-root = "src"
# module-name = "mylib"

[build-system]
requires = ["setuptools>=80.0", "setuptools-scm>=9"]
build-backend = "setuptools.build_meta"

[tool.setuptools_scm]
version_file = "src/sdk/_version.py"
version_scheme = "guess-next-dev"
# version_scheme = "only-version"
# local_scheme = "node-and-date"
local_scheme = "no-local-version"

[tool.setuptools.package-dir]
"" = "src"
# 路径映射，便于用户通过有辨识度的方式导入模块而不是使用sdk或重命名
mylib = "src/sdk"

# [tool.setuptools.packages]
# find = {where = ["src"], include = ["sdk"]}

[tool.setuptools]
packages = ["mylib"]

[tool.uv]
index = [
    { "name" = "tencent", "url" = "https://mirrors.cloud.tencent.com/pypi/simple/" },
    { "name" = "pypi", "url" = "https://pypi.org/simple/" }
]

[dependency-groups]
dev = [
    "build>=1.3.0",
    "twine>=6.2.0",
    "black==25.1.0",
    "commitlint==1.3.0",
    "darker==2.1.1",
    "pre-commit==4.2.0",
    "pytest>=9.0.2",
    "ruff==0.13.1",
    "setuptools-scm>=9.2.2",
    "pyinstaller>=6.17.0",
]

uv run pip install -e .

import sys

print(sys.path)

from mylib import add as mylib_add

def new_add(a: int, b: int) -> int:
    c = mylib_add(a, b)
    print(f"new_add({a}, {b}) = {c}")
    return c

new_add(1,3)

Expected behavior

works

How to Reproduce

1. pyproject.tpml
2. uv pip install -e .
3. uv run main.py

Output

Traceback (most recent call last):
  File "E:\src\python\pyproject-tmpl\main.py", line 6, in <module>
    from mylib import add as mylib_add
ModuleNotFoundError: No module named 'mylib'

[abravalheri]

Hi @xdewx, what is is your directory layout and which files do you have?

For example, can you give us the output of the following command:

tree -I '.venv|dist|build|__pycache__|*.py[cod]|.cache|*.swp|*~|*.egg|*.eggs|.tox|.nox|.mypy_cache|.*.swp'

Alternatively, you could also attempt to create a minimal reproducible example as exemplified in this post.

[xdewx]

Hi @xdewx, what is is your directory layout and which files do you have?

i use src-layout.

.
├── main.py
└── src
    ├── biz
    │   └── __init__.py
    └── sdk
        └── __init__.py

If a minimal reproducible example is needed, it will probably be ready tomorrow.

[abravalheri]

This is an attempt to create a minimal reproducer (I removed all the extra dependencies and I am sticking with the latest version of pip):

> docker run --rm -it python:3.13-bookworm /bin/bash

mkdir /tmp/proj
cd /tmp/proj

cat <<EOF > pyproject.toml
[project]

# 需要更改发布到pypi的包名时改这里
name = "pyproject-tmpl"
dynamic = ["version"]
description = "template python project with necessary configurations"
readme = "README.md"
requires-python = ">=3.10"

[build-system]
requires = ["setuptools>=80.0", "setuptools-scm>=9"]
build-backend = "setuptools.build_meta"

[tool.setuptools.package-dir]
"" = "src"
# 路径映射，便于用户通过有辨识度的方式导入模块而不是使用sdk或重命名
mylib = "src/sdk"

# [tool.setuptools.packages]
# find = {where = ["src"], include = ["sdk"]}

[tool.setuptools]
packages = ["mylib"]
EOF

mkdir -p src/sdk
echo 'def add(a, b): return a+b' > src/sdk/__init__.py


mkdir tests
cat <<EOF > tests/test_alias.py
import sys

print(sys.path)

from mylib import add as mylib_add

def new_add(a: int, b: int) -> int:
    c = mylib_add(a, b)
    print(f"new_add({a}, {b}) = {c}")
    return c

new_add(1,3)
EOF

python -m venv .venv
.venv/bin/python -m pip install -U 'pip==25.3'
.venv/bin/python -m pip install -e .
.venv/bin/python tests/test_alias.py

This example runs without errors and outputs:

['/tmp/proj/tests', '/usr/local/lib/python313.zip', '/usr/local/lib/python3.13', '/usr/local/lib/python3.13/lib-dynload', '/tmp/proj/.venv/lib/python3.13/site-packages']
new_add(1, 3) = 4

i use src-layout.

Please note that because there is a directory remapping in package-dir editable installations cannot be performed using the same method as regular src-layout packages.

So all the limitations documented in https://setuptools.pypa.io/en/latest/userguide/development_mode.html#limitations will apply, and for the effect of the editable installation method, this kind of setup does not qualify simply as src-layout (it is a special case/complex scenario that can not be solved by a simple .pth file under site-packages).

[abravalheri]

Please feel free to update/tweak the reproducer script I posted above until it reproduces the error you are seeing.

[abravalheri]

By the way, the title seems to indicate that you believe that by adding mylib = "src/sdk" to [tool.setuptools.package-dir] you create a package alias.

I wouldn't use the word alias in this case.
The word alias seems to imply that another package already exists, and you are merely "redirecting" during runtime the new package to this other already existing one.

But the way this configuration really works is merely a file/directory mapping.

When you write packages = ["mylib"], you are telling setuptools that you want to add the mylib package to the distribution.
When you write [tool.setuptools.package-dir] mylib = "src/sdk", you are telling setuptools to go find its files inside src/sdk.

There is no "redirection" in runtime, setuptools will just copy the files to a different path inside the distribution during build time.

If you want to have 2 packages and one being "the alias" of the other, with "redirection" during runtime, you will need to write the relevant import statements between the 2 packages.

Not sure if that is what you intended when you used the word alias, but this may be relevant information for you.

[xdewx]

@abravalheri hi, https://github.com/4tst/mre-pyproject-setuptools.git is the MRE.

There are two scenarios, one of which works properly. Even though it runs without issues, VS Code fails to provide code suggestions. Is there any way to fix this?

Also, my wording of "alias" was not accurate — I don’t expect two separate modules to exist.

Could you tell me where I can find the documentation that details setuptools' package mapping, as well as which processes rely on the paths after mapping and which rely on the paths before mapping?

[abravalheri]

There are two scenarios, one of which works properly.

Regarding these two scenarios, you mentioned that one appears to work correctly, while the other appears not to — but in fact both are behaving as expected.

The key point is that setuptools is strictly following the package discovery configuration:

[tool.setuptools.packages.find]
where = ["src"]
include = ["sdk", "sdk*", "mylib", "mylib*"]

This configuration has two explicit constraints:

• Discovery scope: setuptools will only scan directories under the src/ directory.
• Inclusion filter: only packages whose import names match one of:
  sdk, sdk*, mylib, mylib* will be included in the distribution.

In your example, the src directory contains only 2 folders: biz and sdk. As a result, setuptools is instructed to only add the sdk package to the distribution.

Therefore the expected outcome of this configuration is for setuptools to consider only the sdk.

The package-dir = { mylib = "…" } configuration never "kicks in", because from setuptools point of view , setuptools should never include any package other than sdk¹

---

Even though it runs without issues, VS Code fails to provide code suggestions. Is there any way to fix this?

This is a editor/IDE/static-analysis tooling limitation, not a Python or setuptools issue.

When you install the package in editable mode (by using the -e flag), the mylib package does not actually exist in your disk. Instead, the editable installation tells Python where to find the relevant code by introducing dynamic behaviour via import finders.

Python’s import system fully supports this and behaves correctly. This is also something that is described in the PEP that standardised editable imports.

However, static analysis tools operate without executing the import system. They rely almost entirely on static filesystem inspection. As a result, VS Code does not detect the package and therefore provides no code suggestions.

I am not a VS Code user, so I cannot say whether there is a specific configuration that would make it behave correctly in this case. In practice, however, a simpler src‑layout package (without directory remapping) tends to work better out of the box.

If you use a regular installation (without the -e flag), things should also work fine. In that case, an actual mylib directory will be created inside the site-packages directory as part of the installation, and static analysis tools will be able to locate it.

---

Could you tell me where I can find the documentation that details setuptools' package mapping, as well as which processes rely on the paths after mapping and which rely on the paths before mapping?

The most relevant information is in https://setuptools.pypa.io/en/latest/userguide/package_discovery.html

The first section says that you need to specify the packages, and if they don't correspond exactly to the directory structure in the disk, then you also need to specify package-dir.

Footnotes

1. you told it to only include sdk using the package.find configuration. ↩

[xdewx]

@abravalheri Thank you very much for your patient reply. There was a case that didn't work properly in my previous tests, which might be caused by caching, so I'll test it again more carefully

[xdewx]

Footnotes

1. you told it to only include sdk using the package.find configuration. ↩

I see what you mean. You’re saying that in my two test scenarios, even though one of them didn’t meet my expectations (failing to import via mylib), it actually complies with setuptools’ design logic — because I explicitly instructed the finder to only filter modules named sdk.

However, I have a question. Why does package-dir take effect before the finder? Theoretically, it would make more sense if the finder filters modules based on their physical disk names first, and then the file mapping (package-dir) kicks in. Otherwise, issues like mine would arise — where the mapping relationship is clearly configured but ends up conflicting with the finder’s filtering rules. If that were the case, the order of operation for setuptools options should be: find -> package-dir -> packages.

finder is Automatic discovery

[abravalheri]

Why does package-dir take effect before the finder?

As far as I know package-dir take effect after the packages directive.

The logic is the following:

1. You need to tell setuptools which packages you want via the packages configuration.
2. Once setuptools knows which packages you want in the distribution it looks inside package-dir to find out which directories you want mapped.

The find directive is a convenience function that let's setuptools autodiscover the packages based on the directory layout. It is a shortcut for the first step. But if your packages naming don't follow directory layout, then it makes less sense to use it.

[xdewx]

Why does package-dir take effect before the finder?

As far as I know package-dir take effect after the packages directive.

Our understanding maybe consistent, but our expressions differ. Although you said that packages takes effect before package-dir, packages needs to query mylib which relies on the prior execution of package-dir — so my statement should also be correct. However, if we follow the execution sequence of find -> package-dir -> packages, we can ensure that the path is gradually converted from a physical path to a path mapping. This seems more intuitive and can also resolve the issue in my MRE .