Python
PR

Pythonのimportとif __name__ == “__main__”の意味を解説

Pythonのimportとif __name__ == "__main__"の意味を解説
hr
記事内に商品プロモーションを含む場合があります

Python のファイルが増えてくると、「別のファイルに書いた関数を使いたい」「import したら勝手に処理が動いた」「ImportError の意味が分からない」といったことに出会います。サンプルコードの最後によく出てくる if __name__ == "__main__": も、意味が分からないまま書き写している人が多い 1 行です。

この記事では、import の書き方、モジュールを探す順番(sys.path)、__name__ の正体、パッケージと相対 import、よく出るエラーの直し方を説明します。出力は Windows 11・Python 3.12.6 で実際に実行したもので、エラーの File "C:\…\main.py" のフォルダー部分は、ユーザー名が入るため省略しています。

コードはファイル名を合わせて同じフォルダーに保存し、PowerShell でそのフォルダーに移動してから、次のように実行します。

py main.py

モジュールとパッケージとは

Python では、1 つの .py ファイルが 1 つのモジュールです。greet.py というファイルは、ほかのファイルから greet という名前で読み込めます。読み込む操作が import です。

モジュールをフォルダーにまとめたものがパッケージです。標準ライブラリの json も、実は Lib\json\ というフォルダーで、その中の __init__.py が import json で読み込まれます。pip で入れる requests なども同じくパッケージです。

モジュール名は「ファイル名から .py を取ったもの」なので、import greet.py とは書きません。書くと ModuleNotFoundError: No module named 'greet.py'; 'greet' is not a package になりました(「greet の中の py というモジュール」と解釈されるため)。また、import my-tool のようにハイフンを含む名前は SyntaxError: invalid syntax になります。import するファイルの名前は英小文字・数字・アンダースコア(my_tool.py)にしましょう。

import の 4 つの書き方

よく使う書き方は次の 4 つです。

書き方使うときの名前向いている場面
import mathmath.sqrt()基本の形。どのモジュールの関数かが一目で分かる
from math import sqrtsqrt()何度も使う名前を短く書きたいとき
import datetime as dtdt.date()長い名前に別名を付けるとき
from math import *全部そのまま対話モードでの試し打ち以外では使わない

from x import * を避ける理由

from x import * は、モジュールの名前をまとめて取り込みます。便利そうですが、知らないうちに手元の名前を上書きすることがあります。次のコードは、ファイルにメモを書くつもりで組み込み関数の open を使っています。

from os import *

with open("memo.txt", "w") as f:
    f.write("メモ")
Traceback (most recent call last):
  File "C:\…\star.py", line 3, in <module>
    with open("memo.txt", "w") as f:
         ^^^^^^^^^^^^^^^^^^^^^
TypeError: 'str' object cannot be interpreted as an integer

os モジュールにも open という関数(引数に数値のフラグをとる低レベルな関数)があり、それが組み込みの open を上書きしたため、2 つ目の引数 "w" が数値でないというエラーになりました。コードを読んでも open がどこから来たのか分からないのが、この書き方の困るところです。Python 公式チュートリアル 6 章でも、未知の名前が読み込まれて定義済みの名前を上書きするおそれがあるため、ほとんどの場面では使わないと説明されています。

なお、from x import y は「y という名前を自分のファイルにも作る」動きです。テストで関数を差し替えるとき「使われている場所」を指定するのはこのためで、詳しくは unittest.mock の記事で説明しています。

Python がモジュールを探す順番(sys.path)

import random と書いたとき、Python は sys.path というリストに並んだフォルダーを前から順に探し、最初に見つかった random を使います。中身は次のコードで表示できます。

import sys

for p in sys.path:
    print(p)
C:\…\e1
C:\…\Python312\python312.zip
C:\…\Python312\DLLs
C:\…\Python312\Lib
C:\…\Python312
C:\Users\(ユーザー名)\AppData\Roaming\Python\Python312\site-packages
C:\…\Python312\Lib\site-packages

(C:\…\Python312 は C:\Users\(ユーザー名)\AppData\Local\Programs\Python\Python312 を省略したものです。)

1 行目は実行したスクリプト(showpath.py)のフォルダー、その後ろが標準ライブラリ(Lib など)、最後が pip で入れたパッケージの置き場所 site-packages です。公式ドキュメント(チュートリアル 6.1.2 と「sys.path モジュール検索パスの初期化」)の説明では、次の順に作られます。

  1. 実行したスクリプトのあるフォルダー(py -c・py -m・対話モードのときはカレントフォルダー)
  2. 環境変数 PYTHONPATH に書いたフォルダー(設定したときだけ。すべての Python に効くため、公式ドキュメントでも常に設定することには注意が呼びかけられています)
  3. 標準ライブラリのフォルダー
  4. site-packages(pip で入れたパッケージ)
import random と書くと、まず sys.modules に読み込み済みかを確かめ、あればそれを使う。なければ sys.path を前から、実行したスクリプトのフォルダー、PYTHONPATH、標準ライブラリ、site-packages の順に探し、どこにもなければ ModuleNotFoundError になる。スクリプトのフォルダーに自分の random.py があると、標準ライブラリより先に見つかってしまう。
図 1:import random を実行したときに Python がモジュールを探す順番

図の一番上の sys.modules は、読み込み済みのモジュールを覚えておく場所です(後で説明します)。

落とし穴:自分のファイル名を random.py や json.py にする

探す順番の 1 番目が「実行したスクリプトのフォルダー」であることから、初心者がよく引っかかる落とし穴が生まれます。乱数の練習をしようとして、ファイル名を random.py にしてみます。

import random

print(random.randint(1, 6))
py random.py
Traceback (most recent call last):
  File "C:\…\random.py", line 1, in <module>
    import random
  File "C:\…\random.py", line 3, in <module>
    print(random.randint(1, 6))
          ^^^^^^^^^^^^^^
AttributeError: partially initialized module 'random' has no attribute 'randint' (most likely due to a circular import)

1 行目の import random で見つかったのは、標準ライブラリではなく自分自身の random.py でした。それを読み込む途中でまた import random が実行され、まだ randint がない「読み込みが途中(partially initialized)」の自分が返ってきたため、このエラーになります。末尾の「most likely due to a circular import(おそらく循環 import が原因)」は、自分で自分を import している状態を指しています。

別のファイルから使っても同じです。同じフォルダーに練習用の json.py(中身は data = {"name": "Taro"} だけ)があると、app.py の import json は自分の json.py を読み込みます。

import json

print(json.dumps({"ok": True}))
Traceback (most recent call last):
  File "C:\…\app.py", line 3, in <module>
    print(json.dumps({"ok": True}))
          ^^^^^^^^^^
AttributeError: module 'json' has no attribute 'dumps'

「標準ライブラリにあるはずの関数がない」と言われたら、まずこれを疑いましょう。print(json.__file__) で読み込まれたファイルを表示すると、C:\…\e3\json.py と自分のフォルダーのファイルになっていました。

標準ライブラリなら …\Python312\Lib\json\__init__.py と表示されるところです。直し方は、自分のファイルの名前を変える(json_practice.py など)ことです。名前を変えたあと、同じフォルダーの __pycache__ に古い json.cpython-312.pyc が残っていても、元の .py がなければ使われず、{"ok": true} と正しく表示されました。

この PC では、random・json・re・string は同じ名前のファイルで置き換わり、sys・math・time・os は置き換わりませんでした(Python 本体に組み込まれているか起動時に読み込み済みで、sys.path を探す前に見つかるため)。どれが置き換わるかを覚えるより、標準ライブラリや pip で入れたパッケージと同じ名前を付けないのが確実です(pytest.py の例はテスト入門の記事にあります)。

import は 1 回だけ実行される(sys.modules)

import すると、そのモジュールのファイルが上から実行されます。関数の定義(def)も「関数を作る」という実行です。次の greet.py と main.py を用意します。

print("greet.py を読み込み中 __name__ =", __name__)

def hello(name):
    return f"こんにちは、{name}さん"

if __name__ == "__main__":
    print(hello("直接実行"))
import greet
import greet  # 2 回目
print(greet.hello("Python"))
print("main.py の __name__ =", __name__)
greet.py を読み込み中 __name__ = greet
こんにちは、Pythonさん
main.py の __name__ = __main__

import greet を 2 回書いても、「読み込み中」は 1 回しか表示されていません。読み込んだモジュールは sys.modules という辞書に記録され、2 回目以降はそれがそのまま使われるからです(import sys したあと "greet" in sys.modules を表示すると、import の前は False、後は True でした)。

公式ドキュメント(言語リファレンス 5 章「インポートシステム」)でも、import で最初に調べるのは sys.modules で、これまでに読み込んだモジュールのキャッシュ(覚えておく場所)だと説明されています。複数のファイルから同じモジュールを import しても、中身は 1 つを共有します。JavaScript の import も同じ性質で、JavaScript のモジュールの記事で比べられます。

__name__ と if __name__ == “__main__” の意味

上の出力で、greet.py の __name__ は greet、main.py は __main__ でした。__name__ は Python が自動で用意する変数で、直接実行したファイルでは "__main__"、import されたファイルではモジュール名になります。

今度は greet.py を直接実行してみます。

py greet.py
greet.py を読み込み中 __name__ = __main__
こんにちは、直接実行さん

直接実行したときは __name__ が "__main__" になるので、if __name__ == "__main__": の中が動きます。import されたときは "greet" なので動きません。つまりこの 1 行は、「直接実行したときだけ動かしたい処理」を囲む目印です。公式ドキュメント(チュートリアル 6.1.1 と「__main__ — トップレベルのコード環境」)でも、こう書くことでファイルを import できるモジュールとしてもスクリプトとしても使えると説明されています。

書かないと、import しただけで処理が動く

消費税を計算する tax.py に、動作確認のつもりで print を書いたとします。

def with_tax(price):
    return price * 110 // 100

# 動作確認のつもりで書いたコード
print("テスト:", with_tax(1000))

これを別のファイル shop.py から使います。

from tax import with_tax

print("合計:", with_tax(2500))
テスト: 1100
合計: 2750

shop.py では呼んでいない「テスト: 1100」まで表示されました。import でファイル全体が実行されたためです。ここが print ではなく、ファイルの削除や長い計算だったら困ります。動作確認の部分を if __name__ == "__main__": の中に入れます。

def with_tax(price):
    return price * 110 // 100

if __name__ == "__main__":
    print("テスト:", with_tax(1000))

これで py shop.py は「合計: 2750」だけを表示し、py tax.py と直接実行したときだけ「テスト: 1100」が表示されるようになりました。

処理が長くなるときは、def main(): にまとめて、if __name__ == "__main__": の中では main() を呼ぶだけにする形がよく使われます。main() の中で作った変数はローカル変数になるので、ファイルの一番外側(グローバル)に変数が散らばらないという利点もあります(変数のスコープの記事を参照)。なお、Windows で ProcessPoolExecutor(複数のプロセスで並列に計算する仕組み)を使うときは、if __name__ == "__main__": がないとエラーで止まります。理由と実際のエラーは並行処理の記事で説明しています。

パッケージと __init__.py

ファイルが増えたら、フォルダーにまとめてパッケージにします。次の構成で試します。

e5\
├─ main.py
└─ shop\
   ├─ __init__.py
   ├─ tax.py
   └─ cart.py

shop\__init__.py には確認用に print("shop パッケージを読み込み中") だけを書き、shop\tax.py には先ほどの with_tax 関数を置きます。shop\cart.py は次のとおりです。

from .tax import with_tax


def total(prices):
    return with_tax(sum(prices))


if __name__ == "__main__":
    print("cart.py の動作確認:", total([300, 700]))

1 行目の from .tax import with_tax は相対 import です。先頭の点 1 つは「自分と同じパッケージ(shop)の中」を表し、from .. import x と点を 2 つにすると 1 つ上のパッケージを指します。パッケージの外にある main.py からは、点区切りの名前で使います。

from shop.cart import total

print("合計:", total([1200, 800]))
shop パッケージを読み込み中
合計: 2200

shop.cart を読み込む前に、shop\__init__.py が自動で実行されました。__init__.py は「このフォルダーはパッケージです」という印で、空のファイルでも構いません。パッケージを読み込んだときの準備処理や、よく使う名前を from shop.cart import total のように取り込んでおく場所としても使われます。

ちなみに、__init__.py を消しても、この例は同じように動きました(「読み込み中」の表示が出なくなるだけ)。__init__.py のないフォルダーも「名前空間パッケージ」という別の種類のパッケージとして読み込めるためです。ただし公式チュートリアルでは、普通は __init__.py を置くものとして説明されています。自分で作るパッケージには置いておきましょう。

相対 import は直接実行すると ImportError になる

cart.py の動作確認をしようとして、直接実行してみます。

py shop\cart.py
Traceback (most recent call last):
  File "C:\…\shop\cart.py", line 1, in <module>
    from .tax import with_tax
ImportError: attempted relative import with no known parent package

「親パッケージが分からないのに相対 import しようとした」というエラーです。直接実行したファイルは __main__ という単独のモジュールとして読み込まれ、shop パッケージの一員だという情報がないため、「同じパッケージの tax」を探せません。公式チュートリアルでも、メインモジュールの名前は常に "__main__" なので、メインとして使うモジュールでは絶対 import を使うべきだとしています。

パッケージの中のファイルを動かしたいときは、パッケージの外側のフォルダー(e5)で、py -m にモジュール名を渡します。

py -m shop.cart
shop パッケージを読み込み中
cart.py の動作確認: 1100

-m で実行すると、cart.py は「shop パッケージの cart」として読み込まれたうえで、__name__ が "__main__" になります。そのため相対 import も if __name__ == "__main__": の中も両方動きます。

間違えやすい点が 2 つあります。1 つは実行する場所で、shop フォルダーの中に入って py -m cart とすると、同じ ImportError になりました。もう 1 つは書き方で、-m のあとは「ファイルのパス」ではなく「モジュール名」なので、点で区切り .py は付けません。py -m shop.cart.py とすると「Try using ‘shop.cart’ instead of ‘shop.cart.py’ as the module name.」というエラーになりました。

循環 import のエラー

2 つのファイルがお互いを import していると、循環 import(import が輪になっている状態)のエラーになることがあります。users.py と orders.py で試します。

from orders import count_orders


def get_user(user_id):
    return {"id": user_id, "orders": count_orders(user_id)}
from users import get_user


def count_orders(user_id):
    return 3


def order_summary(user_id):
    user = get_user(user_id)
    return f"ユーザー{user['id']}の注文は{user['orders']}件"

上が users.py、下が orders.py です。main.py に from orders import order_summary と print(order_summary(1)) を書いて実行すると、次のようになりました。

Traceback (most recent call last):
  File "C:\…\main.py", line 1, in <module>
    from orders import order_summary
  File "C:\…\orders.py", line 1, in <module>
    from users import get_user
  File "C:\…\users.py", line 1, in <module>
    from orders import count_orders
ImportError: cannot import name 'count_orders' from partially initialized module 'orders' (most likely due to a circular import) (C:\…\orders.py)

トレースバックを上から追うと、main.py → orders.py の 1 行目 → users.py の 1 行目と進み、users.py が orders から count_orders を取り出そうとした時点で止まっています。orders.py はまだ 1 行目を実行中で、count_orders が作られていないからです。import の途中のモジュールも sys.modules には先に登録されるので、中身がそろっていない(partially initialized)モジュールが渡されるのです。直し方は 2 つあります。

直し方 1(おすすめ):共通の部分を別のファイルに分ける。count_orders を新しい counts.py に移し、users.py は from counts import count_orders にします。import の矢印が orders → users → counts の一方通行になり、「ユーザー1の注文は3件」と表示されました。

直し方 2:モジュールごと import し、使うときに名前を取り出す。users.py の 1 行目を import orders にし、関数の中で orders.count_orders(user_id) と書いても動きました。orders.count_orders は関数が呼ばれたときに取り出されるので、その時点では orders の読み込みが終わっています。ただし輪そのものは残るので、まずは直し方 1 のように分け方を見直すのが基本です。

ModuleNotFoundError の原因を切り分ける

ModuleNotFoundError: No module named 'xxx' は、sys.path のどこにも xxx が見つからなかったという意味です。原因は主に次の 4 つです。

原因確かめ方・直し方
名前のつづり間違いimport reqeusts → No module named 'reqeusts'。エラーの名前をよく見る
パッケージを入れていないpy -m pip install パッケージ名 で入れる(pip の記事)
入れた Python と実行している Python が違う仮想環境の有効化忘れなど。下で確かめ方を説明
自作モジュールの場所が sys.path にない別のフォルダーから実行している、パッケージの中のファイルを直接実行しているなど。実行する場所と py -m を見直す

3 つ目は特に多い原因です。この PC のふだんの Python には requests が入っていますが、新しく作った仮想環境(venv)の Python では見つかりませんでした。

.venv\Scripts\python.exe -c "import requests"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'requests'

仮想環境ごとに site-packages が別なので、仮想環境の外で入れたパッケージは中からは見えません(仮想環境の Python で sys.path を表示すると、最後が .venv\Lib\site-packages になっていました)。いま動いている Python がどれかは、import sys のあと print(sys.executable) で確かめられます。

表示されたパスが …\.venv\Scripts\python.exe なら仮想環境の Python、…\Python312\python.exe ならふだんの Python です。パッケージを入れたほうと違えば、仮想環境を有効化して入れ直します。手順は venv の記事にまとめています。

よくある質問

対話モードでモジュールを書き換えたのに、反映されません

import は 1 回だけ実行されるので、ファイルを書き換えてからもう一度 import しても古いままです。importlib.reload(モジュール) で読み込み直せます。VERSION = 1 と書いた conf.py を import したあと、ファイルを VERSION = 2 に書き換えて試すと、import conf をし直しても 1 のままで、importlib.reload(conf) のあとに 2 になりました。ただし、from conf import VERSION で取り出した名前は reload しても古いままなので、迷ったら対話モードを起動し直すのが確実です。

まとめ

  • モジュールは sys.path の順(スクリプトのフォルダー → PYTHONPATH → 標準ライブラリ → site-packages)に探される。標準ライブラリと同じ名前のファイルを作らない
  • __name__ は直接実行すると "__main__"、import されるとモジュール名。直接実行したときだけ動かす処理は if __name__ == "__main__": の中に書く
  • 相対 import を使うファイルは py -m パッケージ名.モジュール名 で実行する。循環 import は共通部分を別ファイルに分けて直す

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました