{ "schemaVersion": "0.11.0", "canonical": "https://www.pystone.net/notes/python-module-import-error-debug/", "atlas": "https://www.pystone.net/?node=python-module-import-error-debug#knowledge-atlas", "markdown": "https://www.pystone.net/notes/python-module-import-error-debug.md", "context": "https://www.pystone.net/notes/python-module-import-error-debug.context.json", "knowledgeVersion": "224c990773de.5fa8af6e39fa", "build": { "siteCommit": "224c990773de166d23a886306577dd90379529ce", "notesCommit": "5fa8af6e39fa3891d1b9b4832bfa6c4e0ecaaf0a", "builtAt": "1970-01-01T00:00:00.000Z", "version": "224c990773de.5fa8af6e39fa" }, "id": "note:python-module-import-error-debug", "slug": "python-module-import-error-debug", "title": "Python模块导入错误排查", "type": "note", "visibility": "public", "idStability": "rename-stable", "author": { "name": "Perrin Yong", "profile": "https://www.pystone.net/profile/" }, "publisher": { "name": "Perrin Yong", "profile": "https://www.pystone.net/profile/" }, "aliases": [], "summary": "Python模块导入错误排查 Terminology", "contentRole": "unspecified", "isMoc": false, "mocRecognition": "none", "generated": false, "attribution": "unspecified", "domain": "10-计算机、信息技术与工程", "tags": [], "mocs": [], "updatedAt": "2021-05-18T11:02:03Z", "contentHash": "be46ede943d9095ca1b010392a4fc023b7c6a4ff5e9661b22b91197bb0ea14a2", "assets": [ { "reference": "assets/0022 - 【Python】How to Fix ModuleNotFoundError and ImportError__1621330950043.png", "url": "/media/a13631e2187aef2a4b70.png", "mediaType": "image/png", "contentHash": "a13631e2187aef2a4b70887179edd5ccda483fe8420a2f0d92989f77eef49c19", "byteLength": 88715, "width": 1351, "height": 707 }, { "reference": "assets/0022 - 【Python】How to Fix ModuleNotFoundError and ImportError__1621331019416.png", "url": "/media/e3a6d8657ccb22a2fc3d.png", "mediaType": "image/png", "contentHash": "e3a6d8657ccb22a2fc3d65dc65dc719d8a6c2cc579d9ba59ee5726f6758232b8", "byteLength": 16391, "width": 663, "height": 196 }, { "reference": "assets/0022%20-%20【Python】How%20to%20Fix%20ModuleNotFoundError%20and%20ImportError__1621330950043.png", "url": "/media/a13631e2187aef2a4b70.png", "mediaType": "image/png", "contentHash": "a13631e2187aef2a4b70887179edd5ccda483fe8420a2f0d92989f77eef49c19", "byteLength": 88715, "width": 1351, "height": 707 }, { "reference": "assets/0022%20-%20【Python】How%20to%20Fix%20ModuleNotFoundError%20and%20ImportError__1621331019416.png", "url": "/media/e3a6d8657ccb22a2fc3d.png", "mediaType": "image/png", "contentHash": "e3a6d8657ccb22a2fc3d65dc65dc719d8a6c2cc579d9ba59ee5726f6758232b8", "byteLength": 16391, "width": 663, "height": 196 } ], "headings": [ { "depth": 1, "text": "Python模块导入错误排查", "anchor": "python模块导入错误排查", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#python%E6%A8%A1%E5%9D%97%E5%AF%BC%E5%85%A5%E9%94%99%E8%AF%AF%E6%8E%92%E6%9F%A5" }, { "depth": 2, "text": "Terminology", "anchor": "terminology", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#terminology" }, { "depth": 2, "text": "How does module import work behind the scenes?", "anchor": "how-does-module-import-work-behind-the-scenes", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#how-does-module-import-work-behind-the-scenes" }, { "depth": 3, "text": "Step 1: sys.modules lookup", "anchor": "step-1-sysmodules-lookup", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#step-1-sysmodules-lookup" }, { "depth": 3, "text": "Step 2: Python Standard Library lookup", "anchor": "step-2-python-standard-library-lookup", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#step-2-python-standard-library-lookup" }, { "depth": 3, "text": "Step 3: sys.path lookup", "anchor": "step-3-syspath-lookup", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#step-3-syspath-lookup" }, { "depth": 2, "text": "Absolute vs Relative imports", "anchor": "absolute-vs-relative-imports", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#absolute-vs-relative-imports" }, { "depth": 3, "text": "absolute imports", "anchor": "absolute-imports", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#absolute-imports" }, { "depth": 3, "text": "relative imports", "anchor": "relative-imports", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#relative-imports" }, { "depth": 2, "text": "Resolution", "anchor": "resolution", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#resolution" }, { "depth": 3, "text": "Use IDE", "anchor": "use-ide", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#use-ide" }, { "depth": 3, "text": "Other cases", "anchor": "other-cases", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#other-cases" }, { "depth": 4, "text": "方法一：命令行", "anchor": "方法一命令行", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#%E6%96%B9%E6%B3%95%E4%B8%80%E5%91%BD%E4%BB%A4%E8%A1%8C" }, { "depth": 4, "text": "方法二：python scripts", "anchor": "方法二python-scripts", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#%E6%96%B9%E6%B3%95%E4%BA%8Cpython-scripts" }, { "depth": 2, "text": "Ref", "anchor": "ref", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#ref" }, { "depth": 2, "text": "%u3010Python%u3011How to Fix ModuleNotFoundError and ImportError", "anchor": "u3010pythonu3011how-to-fix-modulenotfounderror-and-importerror", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#u3010pythonu3011how-to-fix-modulenotfounderror-and-importerror" }, { "depth": 2, "text": "Terminology", "anchor": "terminology-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#terminology-1" }, { "depth": 2, "text": "How does module import work behind the scenes?", "anchor": "how-does-module-import-work-behind-the-scenes-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#how-does-module-import-work-behind-the-scenes-1" }, { "depth": 3, "text": "Step 1: sys.modules lookup", "anchor": "step-1-sysmodules-lookup-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#step-1-sysmodules-lookup-1" }, { "depth": 3, "text": "Step 2: Python Standard Library lookup", "anchor": "step-2-python-standard-library-lookup-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#step-2-python-standard-library-lookup-1" }, { "depth": 3, "text": "Step 3: sys.path lookup", "anchor": "step-3-syspath-lookup-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#step-3-syspath-lookup-1" }, { "depth": 2, "text": "Absolute vs Relative imports", "anchor": "absolute-vs-relative-imports-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#absolute-vs-relative-imports-1" }, { "depth": 3, "text": "absolute imports", "anchor": "absolute-imports-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#absolute-imports-1" }, { "depth": 3, "text": "relative imports", "anchor": "relative-imports-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#relative-imports-1" }, { "depth": 2, "text": "Resolution", "anchor": "resolution-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#resolution-1" }, { "depth": 3, "text": "Use IDE", "anchor": "use-ide-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#use-ide-1" }, { "depth": 3, "text": "Other cases", "anchor": "other-cases-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#other-cases-1" }, { "depth": 4, "text": "方法一：命令行", "anchor": "方法一命令行-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#%E6%96%B9%E6%B3%95%E4%B8%80%E5%91%BD%E4%BB%A4%E8%A1%8C-1" }, { "depth": 4, "text": "%u65B9%u6CD5%u4E8C%uFF1Apython scripts", "anchor": "u65b9u6cd5u4e8cuff1apython-scripts", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#u65b9u6cd5u4e8cuff1apython-scripts" }, { "depth": 2, "text": "Ref", "anchor": "ref-1", "citation": "https://www.pystone.net/notes/python-module-import-error-debug/#ref-1" } ], "claims": [], "outgoing": [], "incoming": [ { "id": "note:programming-languages-and-runtimes", "title": "编程语言与运行时", "url": "https://www.pystone.net/notes/programming-languages-and-runtimes/", "atlas": "https://www.pystone.net/?node=programming-languages-and-runtimes#knowledge-atlas", "label": "编程语言与运行时", "origin": "explicit", "humanReviewed": true, "context": "本层中的“Python模块导入错误排查”导航项", "citation": "https://www.pystone.net/notes/programming-languages-and-runtimes/#%E6%9C%AC%E5%B1%82" } ], "contentMarkdown": "# Python模块导入错误排查\n## Terminology\n\n**python module** - a single file with a .py extension.\n\n**python package** - a folder that contains at least one python module.\n\n\n> - For python2, a package requires a **init**.py file\n> - A python package can contain any number of nested **sub-packages**\n\n\n```\n└── myproject\n\n ├── mypackage\n\n │ ├──\na\n.py\n\n\n └── anotherpackage\n\n ├──\nb\n.py\n\n\n ├── c\n.py\n\n\n └── mysubpackage\n\n └── d.py\n```\n\n\n> Project myproject contains two packages, mypackage and anotherpackage each of which contains a number of python modules, while the latter also contains a sub-package called mysubpackage which in turn contains an additional python module.\n\n\n## How does module import work behind the scenes?\n\n```\nimport\n a\n```\n\n\nPython will execute the above statement in two steps:\n\n\n- Locate, load and initialise (if required) the requested module\n- Define necessary names in the local namespace and corresponding scope\n\nNow Python interpreter is going to follow the next steps in an attempt to **resolve a** .\n\n\n### Step 1: sys.modules lookup\n\nInitially, Python will try to search for the module’s name in **sys.modules** , which is a dictionary that maps module names to modules which have already been loaded. If the name is resolved successfully (which means that another module has already loaded) it will be then be made available to the local namespace otherwise, jump into step 2.\n\n\n![](assets/0022 - 【Python】How to Fix ModuleNotFoundError and ImportError__1621330950043.png)\n\n\n```\nsys : <\nmodule\n\n'sys'\n (built-\nin\n)>\n\nbuiltins : <\nmodule\n\n'builtins'\n (built-\nin\n)>\n\n_frozen_importlib : <\nmodule\n\n'_frozen_importlib'\n (frozen)>\n\n_imp : <\nmodule\n\n'_imp'\n (built-\nin\n)>\n\n_thread : <\nmodule\n\n'_thread'\n (built-\nin\n)>\n\n_warnings : <\nmodule\n\n'_warnings'\n (built-\nin\n)>\n\n_weakref : <\nmodule\n\n'_weakref'\n (built-\nin\n)>\n\n_io : <\nmodule\n\n'io'\n (built-\nin\n)>\n\nmarshal : <\nmodule\n\n'marshal'\n (built-\nin\n)>\n\nnt : <\nmodule\n\n'nt'\n (built-\nin\n)>\n\nwinreg : <\nmodule\n\n'winreg'\n (built-\nin\n)>\n\n_frozen_importlib_external : <\nmodule\n\n'_frozen_importlib_external'\n (frozen)>\n\ntime : <\nmodule\n\n'time'\n (built-\nin\n)>\n\nzipimport : <\nmodule\n\n'zipimport'\n (frozen)>\n\n_codecs : <\nmodule\n\n'_codecs'\n (built-\nin\n)>\n\ncodecs : <\nmodule\n\n'codecs'\n\nfrom\n\n'C:\\\\Users\\\\yh\\\\AppData\\\\Local\\\\Programs\\\\Python\\\\Python39\\\\lib\\\\codecs.py'\n>\n\nencodings.aliases : <\nmodule\n\n'encodings.aliases'\n\nfrom\n\n'C:\\\\Users\\\\yh\\\\AppData\\\\Local\\\\Programs\\\\Python\\\\Python39\\\\lib\\\\encodings\\\\aliases.py'\n>\n```\n\n\n### Step 2: Python Standard Library lookup\n\n> Python Standard Library contains built-in modules (written in C) that provide access to system functionality such as file I/O that would otherwise be inaccessible to Python programmers, as well as modules written in Python that provide standardized solutions for many problems that occur in everyday programming. Some of these modules are explicitly designed to encourage and enhance the portability of Python programs by abstracting away platform-specifics into platform-neutral APIs.\n\n\nIf the name couldn’t be found in sys.modules then Python is going to search for it in Python Standard Library. Again, if the name is resolved then it will be defined in the local namespace otherwise step 3 needs to be followed.\n\n\n### Step 3: sys.path lookup\n\nNow if the module’s name was not found either in sys.modules nor in standard library, Python will finally attempt to resolve it under **sys.path**.\n\n\n![](assets/0022 - 【Python】How to Fix ModuleNotFoundError and ImportError__1621331019416.png)\n\n\n## Absolute vs Relative imports\n\nWe discourage the use of relative imports as they are not as readable as absolute imports\n\n\n```\n└── myproject\n\n ├── mypackage\n\n │ ├──\na\n.py\n\n\n └── anotherpackage\n\n ├──\nb\n.py\n\n\n ├── c\n.py\n\n\n └── mysubpackage\n\n └── d.py\n```\n\n\n### absolute imports\n\n```\nimport\n mypackage.a\n\n\n#\nin\n\nmodule\n a.py\n\nimport\n anotherpackage.mysubpackage.d\n\n\n#\nin\n\nmodule\n b\n\nimport\n anotherpackage.c\n```\n\n\n### relative imports\n\n```\n#\nin\n\nmodule\n a.py\n\nfrom\n ..anotherpackage\nimport\n b\n\nfrom\n ..anotherpackage.b\nimport\n another_function\n\n\n#\nin\n\nmodule\n b\n\nfrom\n .\nimport\n c\n\nfrom\n .c\nimport\n my_function\n```\n\n\n## Resolution\n\n核心原则：\n\n\n- use absolute imports\n- append your project’s root directory to PYTHONPATH\n\n本质是：\n\n\n- 给sys.path中添加路径，使得import时能够找到相应的module。\n- 给sys.modules中添加item\n\n\n### Use IDE\n\nMost modern Python **IDEs** will do the trick automatically but if this is not the case, I am pretty sure there will be such option where you’ll be able to define the PYTHONPATH for your Python application\n\n\n### Other cases\n\n以下两种方法效果相同。\n\n\n#### 方法一：命令行\n\nIf you are running your Python application in any other environment such as **Docker**, **Vagrant** or **inside your virutal environment** you can run the below command in your bash:\n\n\n```\nexport\n PYTHONPATH=\n\"\n${PYTHONPATH}\n:/path/to/your/project/\"\n\n\n## * For Windows\n\nset\n PYTHONPATH=%PYTHONPATH%;C:\\path\\to\\your\\project\\\n```\n\n\n上述命令会将相应的path添加到 **sys.path** 当中。\n\n\n#### 方法二：python scripts\n\nAdd this code in your python scripts:\n\n\n```\nsys.path.\nappend\n(\n/path/\nto\n/your/\nproject\n/)\n```\n\n\n## Ref\n\n\n\n## %u3010Python%u3011How to Fix ModuleNotFoundError and ImportError\n@(10. DevOps)\n\n[TOC]\n\n## Terminology\n\n**python module** - a single file with a .py extension.\n**python package** - a folder that contains at least one python module.\n> * For python2, a package requires a __init__.py file\n> * A python package can contain any number of nested **sub-packages**\n\n```\n%u2514%u2500%u2500 myproject\n %u251C%u2500%u2500 mypackage\n│ ├── a.py\n %u2514%u2500%u2500 anotherpackage\n %u251C%u2500%u2500 b.py\n %u251C%u2500%u2500 c.py\n %u2514%u2500%u2500 mysubpackage\n %u2514%u2500%u2500 d.py\n```\n> Project myproject contains two packages, mypackage and anotherpackage each of which contains a number of python modules, while the latter also contains a sub-package called mysubpackage which in turn contains an additional python module.\n\n## How does module import work behind the scenes?\n```\nimport a\n```\nPython will execute the above statement in two steps:\n* Locate, load and initialise (if required) the requested module\n* Define necessary names in the local namespace and corresponding scope\n\nNow Python interpreter is going to follow the next steps in an attempt to **resolve a** .\n\n### Step 1: sys.modules lookup\nInitially, Python will try to search for the module%u2019s name in **sys.modules** , which is a dictionary that maps module names to modules which have already been loaded. If the name is resolved successfully (which means that another module has already loaded) it will be then be made available to the local namespace otherwise, jump into step 2.\n\n![模块导入排查示意图](assets/0022%20-%20【Python】How%20to%20Fix%20ModuleNotFoundError%20and%20ImportError__1621330950043.png)\n```\nsys : \nbuiltins : \n_frozen_importlib : \n_imp : \n_thread : \n_warnings : \n_weakref : \n_io : \nmarshal : \nnt : \nwinreg : \n_frozen_importlib_external : \ntime : \nzipimport : \n_codecs : \ncodecs : \nencodings.aliases : \n```\n\n### Step 2: Python Standard Library lookup\n> Python Standard Library contains built-in modules (written in C) that provide access to system functionality such as file I/O that would otherwise be inaccessible to Python programmers, as well as modules written in Python that provide standardized solutions for many problems that occur in everyday programming. Some of these modules are explicitly designed to encourage and enhance the portability of Python programs by abstracting away platform-specifics into platform-neutral APIs.\n\nIf the name couldn%u2019t be found in sys.modules then Python is going to search for it in Python Standard Library. Again, if the name is resolved then it will be defined in the local namespace otherwise step 3 needs to be followed.\n\n\n### Step 3: sys.path lookup\nNow if the module%u2019s name was not found either in sys.modules nor in standard library, Python will finally attempt to resolve it under **sys.path**.\n![模块导入排查示意图](assets/0022%20-%20【Python】How%20to%20Fix%20ModuleNotFoundError%20and%20ImportError__1621331019416.png)\n\n## Absolute vs Relative imports\nWe discourage the use of relative imports as they are not as readable as absolute imports\n```\n%u2514%u2500%u2500 myproject\n %u251C%u2500%u2500 mypackage\n│ ├── a.py\n %u2514%u2500%u2500 anotherpackage\n %u251C%u2500%u2500 b.py\n %u251C%u2500%u2500 c.py\n %u2514%u2500%u2500 mysubpackage\n %u2514%u2500%u2500 d.py\n```\n### absolute imports\n```\nimport mypackage.a\n\n## in module a.py\nimport anotherpackage.mysubpackage.d\n\n## in module b\nimport anotherpackage.c\n```\n### relative imports\n```\n## in module a.py\nfrom ..anotherpackage import b\nfrom ..anotherpackage.b import another_function\n\n## in module b\nfrom . import c\nfrom .c import my_function\n```\n\n## Resolution\n\n核心原则：\n* use absolute imports\n* append your project%u2019s root directory to PYTHONPATH\n\n本质是：\n* 给sys.path中添加路径，使得import时能够找到相应的module。\n* %u7ED9sys.modules%u4E2D%u6DFB%u52A0item\n\n### Use IDE\nMost modern Python **IDEs** will do the trick automatically but if this is not the case, I am pretty sure there will be such option where you%u2019ll be able to define the PYTHONPATH for your Python application\n\n### Other cases\n以下两种方法效果相同。\n#### 方法一：命令行\nIf you are running your Python application in any other environment such as **Docker**, **Vagrant** or **inside your virutal environment** you can run the below command in your bash:\n\n```\nexport PYTHONPATH=\"${PYTHONPATH}:/path/to/your/project/\"\n\n## * For Windows\nset PYTHONPATH=%PYTHONPATH%;C:\\path\\to\\your\\project\\\n```\n上述命令会将相应的path添加到 **sys.path** 当中。\n\n#### %u65B9%u6CD5%u4E8C%uFF1Apython scripts\nAdd this code in your python scripts:\n\n```\nsys.path.append(/path/to/your/project/)\n```\n\n\n\n\n\n## Ref\nhttps://towardsdatascience.com/how-to-fix-modulenotfounderror-and-importerror-248ce5b69b1c\n" }