CODE Polyglot / 備忘録

Python のスクリプトを inspect.py と名付けると、標準ライブラリの代わりに読み込まれて ImportError で止まる

スクリプトのあるフォルダが import の探し先の先頭に入るので、標準ライブラリと同じ名前のファイルは標準ライブラリより先に読み込まれます。名前を変えるか、python3 -P で動かします。

起きたこと

URL を1つずつ調べる小さなスクリプトを inspect.py と名付けて動かすと、1行目の from concurrent.futures import ThreadPoolExecutor で ImportError になりました。終了コードは 1 なのに、最後の行の print(「URL を調べます」)も出ていました。

再現の手順

$ printf 'from concurrent.futures import ThreadPoolExecutor\n\nprint("URL を調べます")\n' > inspect.py
$ python3 inspect.py; echo "exit=$?"

出力(パスの前半は「…」に縮めた。それ以外はそのまま):

Traceback (most recent call last):
  File "…/inspect.py", line 1, in <module>
    from concurrent.futures import ThreadPoolExecutor
  File "…/lib/python3.14/concurrent/futures/__init__.py", line 8, in <module>
    from concurrent.futures._base import (FIRST_COMPLETED,
  File "…/lib/python3.14/concurrent/futures/_base.py", line 7, in <module>
    import logging
  File "…/lib/python3.14/logging/__init__.py", line 26, in <module>
    import sys, os, time, io, re, traceback, warnings, weakref, collections.abc
  File "…/lib/python3.14/traceback.py", line 13, in <module>
    import _colorize
  File "…/lib/python3.14/_colorize.py", line 5, in <module>
    from dataclasses import dataclass, field, Field
  File "…/lib/python3.14/dataclasses.py", line 5, in <module>
    import inspect
  File "…/inspect.py", line 1, in <module>
    from concurrent.futures import ThreadPoolExecutor
ImportError: cannot import name 'ThreadPoolExecutor' from partially initialized module 'concurrent.futures' (most likely due to a circular import) (…/lib/python3.14/concurrent/futures/__init__.py)
URL を調べます
exit=1

原因

python3 inspect.py で動かすと、スクリプトのあるフォルダが import の探し先(sys.path)の先頭に入ります。concurrent.futures → logging → traceback → _colorize → dataclasses と読み込みが進み、dataclasses の import inspect が、標準ライブラリではなく自分の inspect.py を読み込みました。

自分の inspect.py は1行目でまた concurrent.futures を読み込もうとしますが、こちらはまだ読み込みの途中なので ThreadPoolExecutor が無く、ImportError になります。最後の「URL を調べます」は、エラーを表示する途中で自分の inspect.py がもう一度読み込まれ、今度は最後まで動いたためとみられます。

直し方

  • ファイルの名前を変える(例: check_urls.py)。名前を決める前に sys.stdlib_module_names で確かめられる
  • 名前を変えられないときは python3 -P inspect.py で動かす。-P はスクリプトのあるフォルダを探し先に入れない(Python 3.11 から)。ただし、同じフォルダの自分のモジュールも読み込まれなくなる

確かめたこと

macOS 26.6・Python 3.14.7(Homebrew)で、2026-11-13 に再現し直しました。

$ mv inspect.py check_urls.py; rm -rf __pycache__; python3 check_urls.py; echo "exit=$?"
URL を調べます
exit=0
$ cp check_urls.py inspect.py; python3 -P inspect.py; echo "exit=$?"
URL を調べます
exit=0
$ python3 -c 'import sys; print("inspect" in sys.stdlib_module_names, "check_urls" in sys.stdlib_module_names)'
True False