Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 38 ยท Projects and Practice

Practice: Packaging Problems and Fixes

Practice diagnosing real packaging problems: ModuleNotFoundError, missing data files, wrong versions, stale environments and build failures, with runnable reproductions and exercises.

Everyone who packages Python code meets the same handful of problems: an import that works on one machine and fails on another, a data file that vanished from the wheel, a package that installs but is the wrong version. Experienced developers are not smarter, they just recognize the pattern. This lesson trains that recognition. For each problem you get the symptom, the usual cause, a way to reproduce it in this page, and the fix.

A diagnostic routine

When something is wrong, answer these questions in order. They solve most cases in a minute:

  1. Which Python is running? python -c "import sys; print(sys.executable)". Many problems are "the wrong interpreter".
  2. Which environment is active? Check which python (where python on Windows) and the prompt prefix (.venv).
  3. What is installed there? python -m pip list (or uv pip list) and python -m pip show NAME for the location and version.
  4. Where is the module imported from? python -c "import NAME; print(NAME.__file__)".
  5. What do the requirements say? python -m pip check lists unsatisfied requirements.

Always call pip as python -m pip. It guarantees pip belongs to the same interpreter you are testing.

flowchart TD
    A["Problem"] --> B{"ImportError?"}
    B -- yes --> C["which python? pip list? __file__?"]
    B -- no --> D{"Wrong behavior or version?"}
    C --> E["wrong env / not installed / name clash / missing __init__"]
    D --> F["stale install / cached wheel / lock out of date"]

Problem 1: it imports from the wrong place

Symptom: you edited the code, but nothing changes. Or import mytool finds an old copy.

Cause: a normal (non-editable) install copied the code into site-packages, so edits to your source folder are invisible. Or a second copy shadows it earlier on sys.path.

Fix: use an editable install during development (pip install -e . or uv sync), and check mytool.__file__.

A very common variant is name shadowing: a file in your own folder named like a library hides the library. Reproduce it:

Python A file that shadows a library

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Looking at __file__ or find_spec(...).origin is the fastest way to see which copy won. Never name your modules random.py, json.py, test.py, email.py and so on.

Problem 2: data files are missing after install

Symptom: the code works from the repository but fails when installed: FileNotFoundError: .../site-packages/mypkg/templates/page.html.

Cause: the build included only Python files, or the code finds data through a path relative to the current directory instead of the package.

Fix: (a) make sure your build backend includes the files (hatchling includes everything inside the package by default; setuptools needs include-package-data and [tool.setuptools.package-data]), (b) read them with importlib.resources, never with open("templates/page.html").

Python Read package data with importlib.resources

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

To verify the fix, open the built wheel and look at its file list (python -m zipfile -l dist/*.whl). If the file is not listed, it was not packaged.

Problem 3: ModuleNotFoundError after a successful install

Symptom: pip install succeeded, but import mytool says ModuleNotFoundError.

Common causes:

  • Installed into a different interpreter than the one running. (Routine questions 1 to 3.)
  • The import name differs from the distribution name: you install pillow but import PIL; install python-dateutil but import dateutil; install scikit-learn but import sklearn.
  • A directory without __init__.py was skipped by an explicit package list. Modern backends find packages automatically, but a hand-written packages = [...] list can miss one.
  • The src layout is configured incorrectly, so the build collected the wrong folder.

You can discover the real import names of an installed distribution:

Python Which modules does a distribution provide?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Problem 4: the wrong version is installed

Symptom: pip show mytool says 1.2.0 but your code behaves like 1.0.

Causes and fixes:

  • A cached or stale wheel: pip install --no-cache-dir --force-reinstall mytool==1.2.0, or rebuild the wheel.
  • The lock file was not regenerated after editing pyproject.toml: run uv lock (CI should use --check).
  • Two environments: see the routine above.
  • A dynamic version from Git tags that you forgot to fetch: shallow clones in CI have no tags (fetch-depth: 0 in actions/checkout), so the version comes out as 0.1.dev1.

Problem 5: a dependency conflict

Symptom: pip says ResolutionImpossible or "conflicting dependencies".

Work through the resolution lesson: read which two packages disagree, and move one of them. Check your own constraints first, because an unnecessary upper bound in your file is the most common culprit.

Problem 6: build failures

Symptom: error: subprocess-exited-with-error while installing, with a long compiler message.

Cause: there is no prebuilt wheel for your platform and Python version, so pip tries to compile from source and lacks a compiler or system headers. This often happens right after a new Python release, or on musl-based distributions such as Alpine.

Fixes: use a Python version for which wheels exist; install the system build tools; use pip install --only-binary=:all: pkg to fail fast instead of compiling; on Docker prefer -slim over Alpine.

Exercises

Try these on your own computer:

  1. Create a src-layout project with one module, install it with pip install -e ., and verify mypkg.__file__ points into src/. Then install it without -e and observe that edits stop appearing.
  2. Add a data file and read it with importlib.resources. Build the wheel and list its contents to prove the file is included.
  3. Break something on purpose: pin requests==2.0 together with a package that needs a newer urllib3, read the error message and fix it.
  4. Make pip check fail by uninstalling a dependency with pip uninstall --yes and no cascade, then repair the environment.
  5. Write down the five-question diagnostic routine on a card for your next debugging session.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should you run pip as python -m pip?

    A bare pip on the PATH may belong to a different Python than the one you are running. python -m pip removes the doubt.
  2. 2. A module imports the wrong code and mymod.__file__ shows a file in your project folder named random.py. What is this called and how do you fix it?

    Your own file comes first on sys.path and hides the library of the same name. Renaming it fixes the problem.
  3. 3. What is the robust way for a package to read one of its own data files?

    importlib.resources locates files relative to the package, wherever it is installed, even inside a zip.
  4. 4. You install scikit-learn and then import scikit_learn fails. Why?

    Distribution names and import names are independent. packages_distributions() shows the mapping.

Summary

  • Diagnose in order: which Python, which environment, what is installed, where the module comes from, what pip check says.
  • Use python -m pip, editable installs for development, and __file__ to find the code actually imported.
  • Read package data with importlib.resources and verify the wheel's file list.
  • Import names and distribution names differ; name shadowing and stale installs are common causes of confusing behavior.
  • Build failures usually mean no wheel exists for your platform; choose a supported Python or install build tools.

Next: Back to the Python Packaging and Tooling course