已通过pip安装的本地自定义Python包显示在pip list中但无法导入的问题求助

Let’s walk through the most likely causes of your ModuleNotFoundError: No module named 'package_a' issue and how to fix them step by step.

1. Verify Your Package Configuration Files (setup.cfg/pyproject.toml) #

The first thing to check is whether your package is being registered with the correct name during installation. Pip uses metadata in setup.cfg or pyproject.toml to name and install your package—if this is misconfigured, pip list might show a different name than what you’re trying to import.

• Open folder_a/setup.cfg and check:
  • Under [metadata], confirm the name field is exactly package_a:

    [metadata]
    name = package_a
    version = ...
    

  • Under [options], ensure the packages field includes your root package. Using find is the easiest way to auto-discover all subpackages:

    [options]
    packages = find
    

• If you’re using pyproject.toml, check the [project] section for the correct name:

  [project]
  name = "package_a"
  version = "..."
  

2. Confirm the Package Was Actually Installed to Your virtualenv #

Even if pip install says it succeeded, it’s worth verifying the package files exist in your virtualenv’s site-packages directory.

• Run this command to get the installation location of package_a:

  pip show package_a
  

• Look for the Location field (e.g., .venv/lib/python3.11/site-packages). Navigate to this directory and confirm there’s a package_a folder containing __init__.py, a.py, and your subpackage_same_name subdirectory.
  • If the folder is missing, your packages configuration in setup.cfg is probably incorrect (it didn’t include package_a during installation).

3. Check How You’re Running a.py #

This is a common pitfall! If you’re directly executing the script file like this:

python ./folder_a/package_a/a.py

Python adds the script’s directory (./folder_a/package_a) to the front of sys.path. When you try to import package_a, Python will look for a subpackage named package_a inside that directory (which doesn’t exist) instead of using the installed package in your virtualenv.

Fix: Run the script as a module instead:

python -m package_a.a

This tells Python to load the installed package_a package from your virtualenv’s site-packages and execute a.py as part of that package.

4. Validate Your virtualenv Paths #

Double-check that you’re actually using the correct virtualenv and that its site-packages is in Python’s path:

• Confirm your virtualenv is active and python/pip point to the right locations:

  which python
  which pip
  

  Both should point to paths inside your .venv directory.
• Print Python’s module search path to ensure the virtualenv’s site-packages is included:

  python -c "import sys; print('\n'.join(sys.path))"
  

  Look for the site-packages path from pip show package_a in the output.

5. Reinstall with Verbose Logging #

If all the above checks pass, try reinstalling the package with verbose logging to catch any hidden issues during installation:

pip install -v ./folder_a

Look for lines in the log that show files being copied to your virtualenv’s site-packages—you should see references to package_a/__init__.py, package_a/a.py, etc. If these lines are missing, your package configuration is still incorrect.

内容的提问来源于stack exchange，提问作者Robert Kirsten