← Back to Home

pip install Reports Success, Then Runs the Old Code

Pythonpackagingsetuptools

Last week I changed one line of packages in pyproject.toml. pip install . returned 0 and the test suite went green. A colleague installed the same wheel we shipped and got ModuleNotFoundError on import. Another rebuilt after a code change, installed, and kept running the previous logic. Both investigations took half a day, and neither was a code bug: the build picked the wrong files, and pip skipped the install, while both returned 0.

I tested this with CPython 3.13.14, setuptools 80.9.0 and pip 26.1.2 on Windows 11, building twelve minimal projects to take each "success" apart, then checked every behaviour against the official documentation. This article contains no affiliate links.

TL;DR:

// FLOW_01Five gates between pyproject.toml and a working import5 NODES01STEP_01write pyproject.toml02STEP_02build the wheel03STEP_03list the wheel contents04STEP_04install into site-packages05STEP_05import at runtimeEND_OF_FLOW
Five gates between pyproject.toml and a working import · diagram drawn from this article
Packaging chain from src to wheel to site-packages
Packaging chain from src to wheel to site-packages · Concept illustration based on this article
PythonJson
Technologies referenced · icons from Simple Icons (CC0)

Split "installed" into two layers

A successful install only means the wheel was unpacked into site-packages. A successful run means the files are there and the version is right. Nothing sits between those two layers: pip never checks whether your import works, and the build backend never checks what a user will be missing after installing.

That is why packaging bugs share one shape: exit code 0, "Successfully" in the log, and the failure postponed to runtime. Six of the cases below are that shape. Two are hard errors, which are easier to live with.

Failure 1: the packages list only knows the names you typed

Here is a src layout with a subpackage at mypkg/sub/:

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

[project]
name = "demo-pkg"
version = "0.1.0"

[tool.setuptools]
package-dir = {"" = "src"}
packages = ["mypkg"]

The wheel comes out at 1,579 bytes and contains only mypkg/__init__.py and mypkg/core.py. mypkg/sub/deep.py is not in it. Installation returns 0 with Successfully installed demo-pkg-0.1.0, and then:

ModuleNotFoundError: No module named 'mypkg.sub'

It is nastier when [project.scripts] points at mypkg.sub.cli:main. The entry point is written into entry_points.txt, the console script is generated, and the failure waits until someone runs it and hits from mypkg.sub.cli import main.

The documentation is blunt about the glob rules for find: patterns must match the full package name, so util matches util/__init__.py but not util/files/__init__.py, and you need util*. The packages array is narrower still: it is a list, not a pattern.

Switch to discovery:

[tool.setuptools.packages.find]
where = ["src"]
include = ["mypkg*"]
namespaces = false

namespaces = false restricts discovery to directories that contain __init__.py. The default is true, which also treats directories without __init__.py as packages, and under a flat layout that tends to pull in more than you intended.

Failure 2: data outside the package stays out of the wheel

The project keeps assets/table.json outside the package, and MANIFEST.in has include assets/*.json. python -m build produces two files:

datapkg-0.2.0.tar.gz               1,335 B   data/table.json: True   assets/table.json: True
datapkg-0.2.0-py3-none-any.whl     1,581 B   data/table.json: True   assets/table.json: False

What the sdist has, the wheel need not have. Reading the file after installation:

FileNotFoundError: [Errno 2] No such file or directory: '...\assets\table.json'

The Non-Package Data Files section of the Data Files documentation closes the door: the old easy_install approach of dropping data into a platform directory is gone, and there is no supported facility to reliably retrieve these resources. The PyPA recommendation is that any data file needed at runtime be included inside the package. In other words, this is not a misconfigured field; the route itself is unsupported.

Two steps to fix it. Move the file into src/datapkg/data/, then read it through importlib.resources instead of joining __file__ by hand, because hand-joined paths break under zip imports and editable installs:

from importlib.resources import files


def load_table():
    return files("datapkg.data").joinpath("table.json").read_text(encoding="utf-8")

files() needs Python 3.9 or newer. Pass encoding explicitly instead of relying on the default.

Failure 3: include-package-data has two different defaults

Same project, one extra line in pyproject.toml:

include-package-data unset:    wheel 1,581 B, contains datapkg/data/table.json
include-package-data = false:  wheel 1,393 B, file missing, no build warning

Installation still returns 0, then load_table() raises FileNotFoundError pointing at site-packages\datapkg\data\table.json. The file was never in the wheel. The size drop works out to 11.9%.

The defaults are split. The documentation says The default value for tool.setuptools.include-package-data is true when projects are configured via pyproject.toml, effective from v61.0.0, while include_package_data defaults to False under setup.cfg and setup.py and was left unchanged for backwards compatibility.

The documentation also gives the exact rule for what reaches a wheel:

(not exclude-package-data) and ((include-package-data and MANIFEST.in) or package-data)

So MANIFEST.in is not sdist-only. With include-package-data true, files matched by MANIFEST.in inside the package go into the wheel as well; with it false, MANIFEST.in alone gets you nothing. To be safe in both directions, declare package-data, which does not depend on MANIFEST.in at all:

[tool.setuptools.package-data]
datapkg = ["data/*.json"]

Failure 4: a same-version wheel is not installed at all

This one fools people. Change the code, keep the version, rebuild, and the filename is identical (quiet_demo-2.0.0-py3-none-any.whl). Install again and the complete output is two lines:

Processing .\dist\quiet_demo-2.0.0-py3-none-any.whl
quiet-demo is already installed with the same version as the provided wheel. Use --force-reinstall to force an installation of the wheel.

Exit code 0, no error, no warning. import quiet returns Q1, the old build. --upgrade behaves the same: rc=0, code unchanged. Only --force-reinstall installs it, and only then do you get Q2.

The control case is instructive. Change the code, keep the version, and run pip install . against the source directory: pip rebuilds and reinstalls, logging Attempting uninstall and Successfully installed. The difference is that a source directory always produces a fresh wheel, while a wheel file you hand to pip first goes through an "already installed at this version" check, and if it matches, pip stops there.

So when "it works locally but the installed copy is old", check the version number first. In CI, either stamp a unique local version on every build or always pass --force-reinstall in the release step.

Failure 5: two distributions, one top-level package

dist-a and dist-b are separate distributions that both provide the top-level package shared/. Install a, then b, and site-packages/shared/ holds three files:

__init__.py   only_a.py   only_b.py

import shared returns B1: the later install overwrote __init__.py. Now uninstall dist-a:

Successfully uninstalled dist-a-1.0.0
site-packages/shared left with: __pycache__  only_b.py
pip list still lists dist-b 1.0.0

The next import raises:

AttributeError: module 'shared' has no attribute 'VALUE'

Not ImportError: the directory still exists, __init__.py does not, so Python treats it as an empty namespace package. And pip list has no idea; dist-b is still listed as installed.

The mechanism is uninstall: pip deletes files listed in the distribution's own RECORD, and both distributions claim shared/__init__.py, so whichever is uninstalled first takes it away. The only real fix is one top-level package per distribution, named after it. Genuine sharing needs PEP 420 implicit namespaces, with non-overlapping subdirectories.

Hard error 1: two top-level packages in a flat layout

This one fails loudly, which is a gift. A project root with alpha/ and beta/ and nothing but [build-system]:

error: Multiple top-level packages discovered in a flat-layout: ['beta', 'alpha'].

The docs explain the guard: setuptools will refuse to create distribution archives with multiple top-level packages or modules, to stop maintenance scripts and similar directories from being published by accident. The documented way out is a src layout or custom discovery.

There is an easy-to-miss precondition: automatic discovery only runs when neither packages nor py-modules is configured. Configure one of them and discovery stops entirely, including that multi-package guard, which is exactly how you end up with Failure 1. Half a configuration is more dangerous than none.

The other trap is the default flat-layout exclusion list: tests, docs, scripts, build, dist, venv, env, requirements, tools and utils are skipped during discovery. Name your package utils/ and it silently disappears from the wheel.

Hard error 2: no setuptools and no build isolation

Since Python 3.12, venv no longer ships setuptools. A fresh 3.13.14 environment reports:

setuptools: False
wheel: False

Running pip install . --no-build-isolation there exits 2 after a long traceback whose last line is:

pip._vendor.pyproject_hooks._impl.BackendUnavailable: Cannot import 'setuptools.build_meta'

Nothing in that text says "install setuptools first". You get BackendUnavailable and a pyproject_hooks call stack, which reads like pip itself is broken. Two ways out:

python -m pip install setuptools wheel
python -m pip install .

Or drop --no-build-isolation and let pip create an isolated environment with the build requirements. The flag means "I have already prepared the build dependencies", and it only helps when that is true.

Failure 6: two answers for one version number

pyproject.toml says version = "1.0.0" while __init__.py hardcodes __version__ = "0.9.9". After installation the two interfaces disagree:

mypkg.__version__      = 0.9.9
metadata.version(...)  = 1.0.0

Maintain both and one will eventually drift. Either keep a single source and read it at build time:

[project]
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "mypkg.__version__"}

Or stop writing __version__ in the package and use importlib.metadata.version("demo-pkg") at runtime. The catch with the first option is that attr is resolved statically: __version__ must be a literal, and a string assembled by a function will not be found.

What an editable install actually changes

After pip install -e . there is no package directory in site-packages, only a .pth file containing one line, the source directory:

D:\work\shadow\src

That line is appended to sys.path, so imports resolve to your working copy. Three things I confirmed: editing an existing file takes effect immediately, adding a module file takes effect immediately, and adding a new top-level package also takes effect immediately. The last one is documented as a side effect: by default an editable install will expose at least all the files that would be available in a regular installation, and to let you iterate it may expose files a regular install would not.

The Limitations section lists what still needs a reinstall: new dependencies, changed entry points, changed metadata. It also states there is no guarantee that files outside the top-level package directory stay accessible.

For behaviour closer to a real install, use strict mode:

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

Strict mode builds a tree of file links under build/__editable__.*, and new files are not exposed. The cost is that deleting that directory breaks imports. The docs also warn that editable installs are not a perfect replacement for regular installs, so verify with a real wheel in a clean environment before shipping.

Troubleshooting: six error strings and their fixes

Error 1 · Multiple top-level packages discovered in a flat-layout

Symptom: pip wheel . fails during metadata preparation with exit code 1. Cause: flat-layout discovery found more than one top-level package and setuptools refuses to build. Fix: move to a src layout, or declare [tool.setuptools.packages.find] where = ["src"] with an include pattern. Do not "solve" it by throwing in a packages = [...] line: that disables discovery and removes the guard along with it.

Error 2 · ModuleNotFoundError: No module named 'mypkg.sub'

Symptom: install succeeds, the top-level import works, and only the subpackage or its entry point fails. Cause: the packages list names mypkg only. Fix: switch to packages.find with a wildcard, then count files with unzip -l dist/*.whl.

Error 3 · FileNotFoundError: No such file or directory: '...\datapkg\data\table.json'

Symptom: works from the source tree, missing after installation. Cause: include-package-data = false, or the file lives outside the package. Fix: move it inside, declare package-data, and read it with importlib.resources.files().

Error 4 · BackendUnavailable: Cannot import 'setuptools.build_meta'

Symptom: exit code 2 under --no-build-isolation, buried in a long traceback with no actionable hint. Cause: venv stopped shipping setuptools in 3.12. Fix: run pip install setuptools wheel first, or drop --no-build-isolation.

Error 5 · AttributeError: module 'shared' has no attribute 'VALUE'

Symptom: after uninstalling a different package, the import raises AttributeError rather than ImportError. Cause: two distributions share a top-level package, and the uninstall removed __init__.py. Fix: reinstall the damaged distribution, then split the top-level packages.

Error 6 · quiet-demo is already installed with the same version as the provided wheel

Symptom: old code keeps running and the exit code is 0. Cause: the same-version wheel was skipped. Fix: --force-reinstall, and make version numbers unique in the release pipeline.

Three checks before you publish

First, inspect the artifacts instead of trusting the exit code. The documentation suggests exactly this:

unzip -l dist/*.whl
tar tf dist/*.tar.gz

Second, install the wheel into a clean environment and run it. Editable installs and source-tree installs both hide missing files; only a wheel in an empty venv matches what users get.

Third, confirm the version has a single source. A duplicate version makes pip skip the install silently, and the only trace is one notice line that a CI job grepping for Successfully will never see.

Two neighbouring topics worth reading: version specifiers, where one missing digit in ~= freezes an entire patch range (PEP 440 pinning, tested), and the audit side once dependencies are installed (pip-audit and SBOM). pyproject.toml is TOML too, and the same value can be parsed into a different type than you expect (YAML defaults and type surprises).

Q: Why do pip install . and pip install dist/x.whl behave differently?

A: The first always builds a fresh wheel from the source tree, so the same version gets reinstalled. The second hands pip an already-built wheel, and pip first checks whether that name and version is installed, then stops with a single notice line if it is.

Q: Is a src layout always better than a flat layout?

A: For projects that rely on discovery, yes: scripts and cache directories in the root cannot be pulled into the distribution by mistake. The cost is that PYTHONPATH=. no longer starts a REPL against the package, so you need an editable install. A flat layout is fine for a single small package.

Q: Can an editable install serve as pre-release validation?

A: No. The documentation says editable installs are not a perfect replacement for regular installs: they may expose extra files, and files outside the package may be unreachable. Before shipping, install the wheel into an empty venv and exercise the entry points and data loading.

👉 Join Xiaomi MiMo Platform: Leading AI model platform with cost-effective inference

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

As an Amazon Associate, I earn from qualifying purchases at no extra cost to you.

☁️ DigitalOcean Cloud ⚡ Vultr VPS 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🧠 AI & LLM Books 🏗️ System Design Books 🐳 Docker & K8s Books 🐧 Linux Admin Books 🐍 Python Books 🗄️ Database Books 🚀 DevOps & SRE Books 🤖 Xiaomi MiMo Platform
← Back to Home