{"id":"14186d830e5e50b0","repo":"pypa/pip","slug":"not-a-package","errorCode":null,"errorMessage":"Not a package:","messagePattern":"Not a package:","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/pip/_vendor/pkg_resources/__init__.py","lineNumber":2462,"sourceCode":"    try:\n        spec = importer.find_spec(packageName)\n    except AttributeError:\n        # capture warnings due to #1111\n        with warnings.catch_warnings():\n            warnings.simplefilter(\"ignore\")\n            loader = importer.find_module(packageName)\n    else:\n        loader = spec.loader if spec else None\n\n    if loader is None:\n        return None\n    module = sys.modules.get(packageName)\n    if module is None:\n        module = sys.modules[packageName] = types.ModuleType(packageName)\n        module.__path__ = []\n        _set_parent_ns(packageName)\n    elif not hasattr(module, '__path__'):\n        raise TypeError(\"Not a package:\", packageName)\n    handler = _find_adapter(_namespace_handlers, importer)\n    subpath = handler(importer, path_item, packageName, module)\n    if subpath is not None:\n        path = module.__path__\n        path.append(subpath)\n        importlib.import_module(packageName)\n        _rebuild_mod_path(path, packageName, module)\n    return subpath\n\n\ndef _rebuild_mod_path(orig_path, package_name, module: types.ModuleType):\n    \"\"\"\n    Rebuild module.__path__ ensuring that all entries are ordered\n    corresponding to their sys.path order\n    \"\"\"\n    sys_path = [_normalize_cached(p) for p in sys.path]\n\n    def safe_sys_path_index(entry):","sourceCodeStart":2444,"sourceCodeEnd":2480,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_vendor/pkg_resources/__init__.py#L2444-L2480","documentation":"Raised as TypeError by _handle_ns(packageName, path_item): while scanning sys.path entries for a namespace package, pkg_resources found the package already present in sys.modules but that module object lacks a __path__ attribute — i.e. it is a regular single-file module, not a package. Namespace packages require __path__, so treating a plain module as a namespace root is an error.","triggerScenarios":"A call path that triggers _handle_ns for a name (e.g. via declare_namespace, fixup_namespace_packages, or Distribution.activate scanning namespace_packages.txt) where the same name is already imported as a non-package module (a .py file, not a package directory).","commonSituations":"Name collision: a namespace package declaration (often from a dependency's namespace_packages.txt) references a name that a different dependency already imported as a regular module. Common in monorepos or when a vendored module shadows a namespace package.","solutions":["Resolve the name collision: rename the conflicting module or the namespace package so they no longer share a dotted name.","Remove the stale namespace_packages.txt / __init__.py declaring the namespace if the project migrated to PEP 420 implicit namespaces.","Ensure the package directory (with __path__) is imported before any same-named module is, so sys.modules holds a real package."],"exampleFix":"// before\n# project_a ships namespace_packages.txt listing 'shared' \n# project_b has a flat module shared.py\nimport shared          # plain module in sys.modules\npkg_resources.declare_namespace('shared')  # TypeError: Not a package\n\n// after\n# rename the flat module or make 'shared' a real package dir with __init__.py\n# then declare_namespace sees a package with __path__","handlingStrategy":"validation","validationCode":"import sys, types\n\ndef safe_namespace_name(name):\n    mod = sys.modules.get(name)\n    if mod is not None and not hasattr(mod, '__path__'):\n        return False  # a plain module occupies this name\n    return True","typeGuard":"import sys\n\ndef name_is_package_or_free(name) -> bool:\n    mod = sys.modules.get(name)\n    return mod is None or hasattr(mod, '__path__')","tryCatchPattern":"try:\n    pkg_resources.fixup_namespace_packages(path_item)\nexcept TypeError as e:\n    if 'Not a package' in str(e):\n        # name collision; skip or rename\n        pass\n    else:\n        raise","preventionTips":["Avoid name collisions between namespace packages and regular modules.","Migrate to PEP 420 implicit namespace packages (remove declare_namespace calls).","Audit namespace_packages.txt in dependencies for stale entries."],"tags":["pkg-resources","namespace","package","type-error","name-collision"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}