<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>Import on KbWen Blog</title>
    <link>https://www.kbwen.com/tags/import/</link>
    <description>Articles and notes on AI systems, machine learning, Python, data engineering, and software development.</description>
    <generator>Hugo</generator>
    <language>zh-tw</language>
    <image>
      <url>https://www.kbwen.com/images/og-default.png</url>
      <title>KbWen Blog</title>
      <link>https://www.kbwen.com/</link>
    </image>
    
    <lastBuildDate>Thu, 05 Nov 2026 09:18:57 +0800</lastBuildDate><atom:link href="https://www.kbwen.com/tags/import/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>Python 出現 attempted relative import with no known parent package 是怎麼回事</title>
      <link>https://www.kbwen.com/python-relative-import-no-known-parent-package/</link>
      <pubDate>Thu, 05 Nov 2026 09:18:57 +0800</pubDate><dc:creator>KbWen</dc:creator>
      <guid>https://www.kbwen.com/python-relative-import-no-known-parent-package/</guid>
      <description>同一個檔案直接執行會出現這個錯誤，改用 python -m 執行卻正常，來看看兩次執行差在哪裡。</description>
      <content:encoded><![CDATA[<p>為什麼同一個 <code>main.py</code>，用 <code>python pkg/main.py</code> 執行會丟出 <code>ImportError: attempted relative import with no known parent package</code>，換成 <code>python -m pkg.main</code> 卻能正常跑完？檔案裡寫了 <code>from . import helper</code> 之類的相對匯入，再照原本的習慣直接執行檔案，就常常會碰到這個錯誤。</p>
<p>重現用的例子：<code>demo</code> 資料夾底下只有一個 <code>pkg</code> 套件，裡面放 <code>__init__.py</code>（空檔案）、<code>helper.py</code> 和 <code>main.py</code>：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># pkg/helper.py</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">greet</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="s2">&#34;hello from helper&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># pkg/main.py</span>
</span></span><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="s2">&#34;__name__ =&#34;</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="vm">__name__</span><span class="p">))</span>
</span></span><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="s2">&#34;__package__ =&#34;</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="n">__package__</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">helper</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="n">helper</span><span class="o">.</span><span class="n">greet</span><span class="p">())</span>
</span></span></code></pre></div><h2 id="兩次輸出">兩次輸出</h2>
<p>在 <code>demo</code> 這一層，兩種方式各執行一次（Python 3.14）：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">$ python pkg/main.py
</span></span><span class="line"><span class="cl">__name__ = &#39;__main__&#39;
</span></span><span class="line"><span class="cl">__package__ = None
</span></span><span class="line"><span class="cl">Traceback (most recent call last):
</span></span><span class="line"><span class="cl">  File &#34;.../demo/pkg/main.py&#34;, line 4, in &lt;module&gt;
</span></span><span class="line"><span class="cl">    from . import helper
</span></span><span class="line"><span class="cl">ImportError: attempted relative import with no known parent package
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">$ python -m pkg.main
</span></span><span class="line"><span class="cl">__name__ = &#39;__main__&#39;
</span></span><span class="line"><span class="cl">__package__ = &#39;pkg&#39;
</span></span><span class="line"><span class="cl">hello from helper
</span></span></code></pre></div><p>第一行都是 <code>__name__ = '__main__'</code>。這裡就有個意外，用了 <code>-m</code>，模組名稱也沒有變成 <code>pkg.main</code>，<code>main.py</code> 一樣是主模組，所以檔案底下如果有 <code>if __name__ == &quot;__main__&quot;:</code>，兩種執行方式都會進去。</p>
<p>不同的地方在第二行：直接執行時 <code>__package__</code> 是 <code>None</code>，用 <code>-m</code> 執行時是 <code>'pkg'</code>。Python 3.6 以後，匯入時會先看 <a href="https://docs.python.org/3.14/reference/datamodel.html#module.__package__"><code>__spec__.parent</code></a>，沒有才退回 <code>__package__</code>；用 <code>-m</code> 執行時兩者都是 <code>'pkg'</code>）。<code>from . import helper</code> 的 <code>.</code> 指的是目前所在的套件。直接執行時 <code>__package__</code> 是 <code>None</code>，Python 不知道 <code>.</code> 是哪一個套件，錯誤訊息裡的 no known parent package 這段的來源。</p>
<p>那 <code>-m</code> 怎麼知道套件是 <code>pkg</code>？<code>-m</code> 會先透過一般的匯入機制把模組找出來，再當成 <code>__main__</code> 模組執行（<a href="https://docs.python.org/3/using/cmdline.html#cmdoption-m">命令列的說明</a>）。指令裡的 <code>pkg.main</code> 本來就是模組名稱，從輸出可以看到，名稱前面 <code>pkg</code> 就成了 <code>__package__</code>。直接給檔案路徑時，<code>pkg/main.py</code> 只是一個要執行的檔案，雖然旁邊有 <code>__init__.py</code>，<code>__package__</code> 還是 <code>None</code>。</p>
<p>另外，<code>-m</code> 會把目前所在的資料夾加到 <code>sys.path</code> 開頭，所以要在 <code>pkg</code> 的上一層（<code>demo</code>）執行（這一步很容易漏掉，先 <code>cd</code> 進 <code>pkg</code> 再下 <code>python -m pkg.main</code>，會看到 <code>No module named 'pkg'</code>）。</p>
<h2 id="改執行指令或是改匯入">改執行指令，或是改匯入</h2>
<p>假設平常都是在 <code>demo</code> 層開終端機，程式其實一行都不用動，把指令換成 <code>python -m pkg.main</code> 就可以了。</p>
<p>Python 教學的<a href="https://docs.python.org/3/tutorial/modules.html#intra-package-references">模組章節</a>則是建議另一條路：主模組沒有套件，所以要當主模組執行的模組，一律用絕對匯入。等等，剛剛用 <code>-m</code> 跑的 <code>main.py</code> 明明也是主模組，相對匯入卻沒有出錯？主模組沒有套件，比較貼近直接用檔名執行的情況，那時 <code>__package__</code> 確實是 <code>None</code>。用 <code>-m</code> 就不一樣了，<code>__package__</code> 當初加進來，本來就是為了讓 <code>-m</code> 執行的模組能直接用相對匯入。所以教學的說法偏保守，不代表 <code>-m</code> 底下的相對匯入有問題。</p>
<p>不過改成絕對匯入，也不是把 <code>main.py</code> 裡那一行換掉就能直接執行。<code>from . import helper</code> 改成 <code>from pkg import helper</code>，再執行 <code>python pkg/main.py</code>，錯誤會變成 <code>ModuleNotFoundError: No module named 'pkg'</code>。而直接執行檔案時，Python 會把檔案所在的資料夾加到 <code>sys.path</code> 開頭，也就是 <code>pkg</code> 本身，而不是上一層的 <code>demo</code>，所以找不到 <code>pkg</code>。</p>
<p>入口檔案改放在 <code>demo</code> 這一層，<code>pkg</code> 就找得到了，比如另外放一個 <code>run.py</code>：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># run.py</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">pkg</span> <span class="kn">import</span> <span class="n">main</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">$ python run.py
</span></span><span class="line"><span class="cl">__name__ = &#39;pkg.main&#39;
</span></span><span class="line"><span class="cl">__package__ = &#39;pkg&#39;
</span></span><span class="line"><span class="cl">hello from helper
</span></span></code></pre></div><p>這次發現 <code>__name__</code> 變成 <code>'pkg.main'</code> 了。主模組換成 <code>run.py</code>，它用絕對匯入載入 <code>pkg.main</code>，<code>pkg/main.py</code> 變成只是被匯入的模組，裡面的 <code>from . import helper</code> 照樣能用。</p>
<p>碰到這個錯誤，我覺得最容易誤會的地方，是它看起來很像 import 寫錯了，但前面兩次執行，發現變的只有執行的方式。</p>
]]></content:encoded>
    </item>
    
  </channel>
</rss>
