Python importの使い方｜自作モジュールとエラー対処

Pythonの import とは、別のファイル（モジュール）やフォルダ（パッケージ）に書かれた関数・クラス・変数を、自分のコードから使えるようにする文です。 標準ライブラリも、pip で入れたライブラリも、自分で書いたファイルも、同じ import 文で読み込みます。

書き方そのものは短いのですが、自作のファイルを読み込もうとすると ModuleNotFoundError や attempted relative import に出会うことがよくあります。原因のほとんどは「Python がどのフォルダを探しているか（sys.path）」と「どうやって実行したか」の 2 点に集約されます。

この記事では、import 構文の一覧表、フォルダ構成図つきの自作モジュール・パッケージの作り方、そして代表的なエラーの再現と原因別の解決手順を、すべて手元で実行した結果つきで紹介します。検証は Python 3.11.15、一部のエラーメッセージの比較に Python 3.14.7 を使いました。出力中のパスは /home/user/... に置き換えています。

importの早見表

構文の一覧

エラーから原因を引く表

基本の使い方：自作モジュールを import する

モジュールとは、.py ファイル 1 つのことです。 ファイル名から .py を取ったものがモジュール名になります。まずは同じフォルダに 2 つのファイルを置く、いちばん単純な形から始めます。

shop/
├── calc.py     ← 自作モジュール
└── main.py     ← 実行するファイル

calc.py：

TAX_RATE = 0.1

def add_tax(price):
    return int(price * (1 + TAX_RATE))

def _round(x):
    return round(x)

if __name__ == "__main__":
    print("calc.py を直接実行:", add_tax(1000))

main.py：

import calc
import calc as c
from calc import add_tax
from calc import add_tax as tax, TAX_RATE

print(calc.add_tax(1000))
print(c.TAX_RATE)
print(add_tax(200), tax(300), TAX_RATE)
print(calc.__name__, __name__)

cd shop
python3 main.py

実行結果：

1100
0.1
220 330 0.1
calc __main__

4 つの書き方はどれも同じ calc.py を読み込んでいます。違いは「どの名前で使えるようになるか」だけです。

import と from の使い分け

迷ったら import モジュール名、頻繁に使うものだけ from ... import 名前 とすると、読みやすさと書きやすさのバランスが取れます。

import は最初の 1 回だけ実行される

同じモジュールを何度 import しても、ファイルの中身が実行されるのは最初の 1 回だけです。読み込んだモジュールは sys.modules という辞書に記録され、2 回目以降はそこから取り出されます。

import calc, sys
import calc
print(calc.__name__, 'calc' in sys.modules, calc.__file__)

calc True /home/user/shop/calc.py

モジュール.__file__ を表示すると、実際にどのファイルが読み込まれたかがわかります。 意図しないファイルを読んでいないか調べるときの、いちばん確実な方法です。対話モードでファイルを書き換えたあとに読み直したいときは importlib.reload(calc) を使います。

if __name__ == "__main__" の意味

先ほどの出力の最後の行は calc __main__ でした。__name__ は、そのファイルが「どう読み込まれたか」を表す変数です。

この仕組みを使うと、「直接実行されたときだけ動かす処理」を書けます。

python3 calc.py

calc.py を直接実行: 1100

main.py から import したときには、この行は表示されませんでした。import される側のファイルでは、関数とクラスの定義だけをトップレベルに置き、動作確認や起動の処理は if __name__ == "__main__": の中に入れると、import しただけで処理が走ることを防げます。

パッケージを作る：フォルダで整理する

ファイルが増えてきたら、フォルダに分けて整理します。モジュールを入れたフォルダを「パッケージ」と呼びます。

shop/                      ← ルート（ここで実行する）
├── run.py
├── app/
│   ├── __init__.py
│   ├── cli.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── item.py
│   │   └── order.py
│   └── utils/
│       ├── __init__.py
│       └── money.py
└── scripts/
    └── report.py

app/__init__.py（動きを見るために print を入れています）：

print("app/__init__.py が実行されました")

app/utils/money.py（app/utils/__init__.py は空のファイル）：

def add_tax(price, rate=0.1):
    return int(price * (1 + rate))

app/models/item.py：

class Item:
    def __init__(self, name, price):
        self.name = name
        self.price = price

app/models/order.py（相対 import を使用）：

from .item import Item
from ..utils.money import add_tax


class Order:
    def __init__(self):
        self.items: list[Item] = []

    def add(self, item: Item):
        self.items.append(item)

    def total(self):
        return add_tax(sum(i.price for i in self.items))

app/models/__init__.py：

from .item import Item
from .order import Order

__all__ = ["Item", "Order"]

run.py：

from app.models import Item, Order

order = Order()
order.add(Item("ノート", 300))
order.add(Item("ペン", 120))
print("合計:", order.total())

cd shop
python3 run.py

app/__init__.py が実行されました
合計: 462

__init__.py の役割

__init__.py は、そのフォルダが import されたときに最初に実行されるファイルです。 上の結果でも、from app.models import ... と書いただけで app/__init__.py が実行されています。

app/models/__init__.py で Item と Order を引き上げているので、使う側は from app.models.item import Item と奥まで書かずに、from app.models import Item と短く書けます。

絶対 import と相対 import

パッケージの中から別のモジュールを読み込む書き方は 2 種類あります。

相対 import のドットは、フォルダの . .. と同じ感覚で読めます。

相対 import は from で始まる形だけで、import .item とは書けません。PEP 8 では絶対 import を基本とし、パッケージ内部の込み入った構成では相対 import も使ってよい、としています。チームでどちらかに決めておくと読みやすくなります。

__init__.py がないフォルダ：名前空間パッケージ

Python 3.3 以降は、__init__.py がないフォルダも import できます。これを名前空間パッケージと呼びます。手元で、__init__.py のない nsdemo/ フォルダと、ある app/ フォルダを比べました。

import nsdemo, nsdemo.mod
print(nsdemo, nsdemo.mod.X)
import app
print(app)

<module 'nsdemo' (<_frozen_importlib_external.NamespaceLoader object at 0x7f7cab70ce50>)> 1
app/__init__.py が実行されました
<module 'app' from '/home/user/shop/app/__init__.py'>

名前空間パッケージは、別々の場所にある同じ名前のフォルダを 1 つのパッケージとして合成できるのが本来の用途です。part1/acme/tools/ と part2/acme/docs/ を両方 sys.path に入れて確認しました。

import acme, acme.tools, acme.docs
print(acme.tools.NAME, acme.docs.NAME)
print(acme.__file__)
print(acme.__path__)

tools docs
None
_NamespacePath(['/home/user/ns/part1/acme', '/home/user/ns/part2/acme'])

ふつうのアプリでは、__init__.py を置いて通常のパッケージにするのがおすすめです。 pytest や mypy、パッケージ化のツールがフォルダを見つけやすくなり、置き忘れによる挙動の違いに悩まずに済みます。

from module import * と __all__

from モジュール import * で読み込まれる名前は、次のルールで決まります。

calc.py（__all__ なし）で確かめると、_round は除かれました。

from calc import *
print([n for n in dir() if not n.startswith('__')])

['TAX_RATE', 'add_tax']

次に、__all__ を定義した shapes.py です。

__all__ = ["area"]

PI = 3.14159


def area(r):
    return PI * r * r


def perimeter(r):
    return 2 * PI * r

from shapes import *
print(area(1))
print('perimeter' in dir(), 'PI' in dir())
from shapes import perimeter
print(perimeter(1))

3.14159
False False
6.28318

__all__ は import * の対象を絞るだけで、名前を指定した import は制限しません。 「このモジュールが外向けに公開している名前の一覧」を示す役割もあり、エディタの補完や静的解析ツールもこの一覧を参照します。なお、import * を関数の中に書くと SyntaxError: import * only allowed at module level になります。

Python はどこを探すのか：sys.path

import のエラーを理解するいちばんの近道は、sys.path（モジュールを探すフォルダのリスト） を知ることです。Python は import 文に出会うと、このリストを先頭から順に探し、最初に見つかったものを読み込みます。

showpath.py：

import sys
for p in sys.path:
    print(repr(p))

cd shop
python3 showpath.py

'/home/user/shop'
'/usr/lib/python311.zip'
'/usr/lib/python3.11'
'/usr/lib/python3.11/lib-dynload'
'/root/.local/lib/python3.11/site-packages'
'/usr/local/lib/python3.11/dist-packages'
'/usr/lib/python3/dist-packages'

大事なのは先頭の 1 行が、実行方法によって変わることです。

「カレントディレクトリが探される」と思いがちですが、ファイルを直接実行したときに探されるのは、そのファイルが置かれたフォルダです。 この違いが、次の章のエラーの原因になります。

エラーの再現と解決

ModuleNotFoundError: No module named 'app'（実行場所と sys.path）

scripts/report.py から app パッケージを使おうとした例です。

import sys
print("sys.path[0] =", sys.path[0])
from app.models import Item
print(Item("消しゴム", 80).name)

cd shop
python3 scripts/report.py

sys.path[0] = /home/user/shop/scripts
Traceback (most recent call last):
  File "/home/user/shop/scripts/report.py", line 3, in <module>
    from app.models import Item
ModuleNotFoundError: No module named 'app'

shop/ で実行しているのに、app が見つかりません。sys.path の先頭が shop/scripts になっていて、その中に app フォルダがないからです。解決の方法は 3 つあり、どれも手元で動作を確認しました。

解決 1：python -m で実行する

cd shop
python3 -m scripts.report

sys.path[0] = /home/user/shop
app/__init__.py が実行されました
消しゴム

-m は「モジュール名を指定して実行する」オプションです。カレントディレクトリが sys.path の先頭に入るので、ルートのフォルダで実行すれば app が見つかります。指定はファイルのパスではなく、.py を付けないドット区切りの名前です。

解決 2：PYTHONPATH でルートを追加する

cd shop
PYTHONPATH=. python3 scripts/report.py

sys.path[0] = /home/user/shop/scripts
app/__init__.py が実行されました
消しゴム

Windows の PowerShell では $env:PYTHONPATH = "." を先に実行します。

解決 3：pip install -e . でパッケージとして登録する

ルートに pyproject.toml を置き、編集可能インストールをすると、どのフォルダから実行しても import できるようになります。

[build-system]
requires = ["setuptools>=77"]
build-backend = "setuptools.build_meta"

[project]
name = "shop-app"
version = "0.1.0"
requires-python = ">=3.10"

[tool.setuptools.packages.find]
include = ["app*"]

cd shop
python -m pip install -e .      # venv を有効化した状態で
cd /tmp
python /home/user/shop/scripts/report.py

sys.path[0] = /home/user/shop/scripts
app/__init__.py が実行されました
消しゴム

pip list には shop-app 0.1.0 /home/user/shop と、元のフォルダの場所つきで表示されました。pip のコマンドの詳細は別記事「pipコマンド一覧」にまとめています。

ImportError: attempted relative import with no known parent package

相対 import を含むファイルを、直接実行したときのエラーです。app/cli.py を用意しました。

from .models import Item, Order


def main():
    order = Order()
    order.add(Item("付箋", 200))
    print("合計:", order.total())


if __name__ == "__main__":
    main()

cd shop
python3 app/cli.py

Traceback (most recent call last):
  File "/home/user/shop/app/cli.py", line 1, in <module>
    from .models import Item, Order
ImportError: attempted relative import with no known parent package

直接実行されたファイルは __main__ という名前の単独のモジュールとして扱われ、「自分がどのパッケージに属しているか」の情報を持ちません。 そのため、.（自分のパッケージ）を解決できずに止まります。

解決は、ルートのフォルダから -m で実行することです。

cd shop
python3 -m app.cli

app/__init__.py が実行されました
合計: 220

-m で実行すると、Python は app.cli がパッケージ app の一員であることを把握するので、相対 import が解決されます。VS Code などのエディタの実行ボタンは「ファイルを直接実行」する設定になっていることが多いので、実行構成で「モジュールとして実行」を選ぶと同じ結果になります。

似たエラーに attempted relative import beyond top-level package があります。これは、.. の数が多く、パッケージの最上位を越えたときに出ます。app/utils/ の中のファイルに from ....x import y と書いて import すると、手元でも次のように表示されました。

ImportError: attempted relative import beyond top-level package

ドットの数を数え直すか、絶対 import（from app.xxx import ...）に書き換えると解決します。

circular import（循環 import）

2 つのモジュールがお互いを import し合うと起こります。

member.py：

from team import Team


class Member:
    def __init__(self, name):
        self.name = name

    def team(self):
        return Team("開発")

team.py：

from member import Member


class Team:
    def __init__(self, name):
        self.name = name
        self.members = [Member("佐藤")]

python3 -c "import member"

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/home/user/circ/member.py", line 1, in <module>
    from team import Team
  File "/home/user/circ/team.py", line 1, in <module>
    from member import Member
ImportError: cannot import name 'Member' from partially initialized module 'member' (most likely due to a circular import) (/home/user/circ/member.py)

起きていることを順に追うと、次のとおりです。

sequenceDiagram
    participant P as Python
    participant M as member.py
    participant T as team.py
    P->>M: import member（1行目を実行）
    M->>T: from team import Team
    T->>M: from member import Member
    Note over M: まだ1行目の途中。Member は未定義
    M-->>T: ImportError（partially initialized）

partially initialized module（初期化の途中のモジュール）という言葉が、循環 import の目印です。 import team の形で読み込んで属性を使った場合は、AttributeError: partially initialized module 'member' has no attribute 'DEFAULT' (most likely due to a circular import) という形で現れました。

解決方法は次の 3 つです。

1 つ目の方法で member.py を直しました。

class Member:
    def __init__(self, name):
        self.name = name

    def team(self):
        from team import Team   # 使う時点で import する
        return Team("開発")

from member import Member
t = Member('鈴木').team()
print(t.name, [m.name for m in t.members])

開発 ['佐藤']

型ヒントのためだけに相手のクラスが必要な場合は、次の書き方が使えます（標準ライブラリの typing の機能で、公式ドキュメントで確認した書き方です）。

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from team import Team   # 型チェックのときだけ読み込まれる

循環が何度も起こるときは、「2 つのモジュールの役割が重なっている」というサインでもあります。依存の向きを一方通行にする（たとえば models は utils を使うが、utils は models を使わない）と決めておくと、構成がすっきりします。

ImportError: cannot import name

モジュールは見つかったものの、その中に指定した名前がないときのエラーです。

python3 -c "from calc import add_taxx"

ImportError: cannot import name 'add_taxx' from 'calc' (/home/user/shop/calc.py)

Python 3.14.7 では、候補も表示されました。

ImportError: cannot import name 'add_taxx' from 'calc' (/home/user/shop/calc.py). Did you mean: 'add_tax'?

エラー文の末尾のかっこ内に、実際に読み込まれたファイルのパスが出ます。 ここが意図したファイルかどうかを最初に見ます。

標準ライブラリと同名のファイル（random.py）

自作のファイルに random.py、json.py、test.py、email.py など、標準ライブラリと同じ名前を付けると、sys.path の先頭にある自作ファイルのほうが先に見つかり、標準ライブラリが読み込まれなくなります。

random.py：

import random

print(random.randint(1, 6))

python3 random.py

Python 3.11.15 の結果：

Traceback (most recent call last):
  File "/home/user/shadow/random.py", line 1, in <module>
    import random
  File "/home/user/shadow/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)

import random が自分自身を読み込んでいるため、循環 import と同じ形のメッセージになります。Python 3.14.7 では、原因と対処がそのまま表示されました。

AttributeError: module 'random' has no attribute 'randint' (consider renaming '/home/user/shadow/random.py' since it has the same name as the standard library module named 'random' and prevents importing that standard library module)

別のファイルから読み込む形でも同じです。フォルダに json.py を置いた状態で import json すると、__file__ は自作のファイルを指していました。

/home/user/shadow/json.py          ← json.py がある状態
/usr/lib/python3.11/json/__init__.py   ← json.py を削除したあと

対処は、自作ファイルの名前を変えることです（例：random.py を dice.py に）。同じフォルダに __pycache__ があれば、合わせて削除しておくと確実です。「標準ライブラリの関数がないと言われる」ときは、print(モジュール.__file__) で読み込み元を確認すると、すぐに気付けます。

No module named 'requests'（pip 未導入・venv 違い）

外部ライブラリが見つからないケースです。新しく作った venv の Python と、OS の Python で比べました。

python3 -m venv ../v1
../v1/bin/python -c "import requests"
python3 -c "import requests; print(requests.__version__)"

ModuleNotFoundError: No module named 'requests'
2.34.2

同じマシンでも、Python ごとにインストール済みのライブラリは別々です。 OS の Python には入っていても、venv の Python には入っていません。「pip install したのに見つからない」ときは、インストールした先と、実行している Python がずれています。

確認の手順は次のとおりです。

python -c "import sys; print(sys.executable)"   # 実行している Python
python -m pip --version                          # その Python の pip
python -m pip list                               # その Python に入っているもの
python -m pip install requests                   # その Python に入れる

手元の venv では、sys.executable が /home/user/v1/bin/python、pip list は pip と setuptools だけでした。pip install ではなく python -m pip install と書くと、実行に使う Python と同じ場所へ確実に入ります。

import する名前と、pip で指定する名前が異なるライブラリの例です。

venv の作り方・有効化のコマンドは、別記事「Python venvの使い方」で OS 別に紹介しています。

原因別チェックリスト

import のエラーが出たら、上から順に確認します。

import できるかどうかだけを調べたいときは、importlib.util.find_spec が便利です。見つかれば場所、見つからなければ None が返りました。

import importlib.util
print(importlib.util.find_spec('app.models').origin)
print(importlib.util.find_spec('nothing_here'))

/home/user/shop/app/models/__init__.py
None

import 文の書き方の作法

PEP 8（Python の公式スタイルガイド）に沿った並べ方です。

# 1. 標準ライブラリ
import json
import sys
from pathlib import Path

# 2. 外部ライブラリ
import requests

# 3. 自作のモジュール
from app.models import Item, Order
from app.utils.money import add_tax

よくある質問

Q. __init__.py は必ず必要ですか？ A. Python 3.3 以降は、なくても import できます（名前空間パッケージ）。ただし、初期化の処理や名前の引き上げが書けず、ツールによってはフォルダの扱いが変わります。通常のアプリでは、空のファイルでよいので置いておくのがおすすめです。

Q. 1 つ上のフォルダにあるモジュールを import するには？ A. 「上のフォルダ」ではなく、「ルートのフォルダから見た名前」で考えると整理できます。ルートで python -m パッケージ.モジュール として実行すれば、どのファイルからも from app.utils.money import add_tax のように絶対 import で書けます。別のフォルダからも使いたい場合は pip install -e . で登録します。

Q. import a.b.c と from a.b import c は何が違いますか？ A. 読み込まれるものは同じで、使うときの名前が違います。前者は a.b.c.func()、後者は c.func() と書きます。import a.b.c as c と書けば、後者と同じ名前で使えます。

Q. Jupyter Notebook で自作モジュールを書き換えても反映されません。 A. import は最初の 1 回だけ実行されるためです。importlib.reload(モジュール) で読み直すか、カーネルを再起動します。IPython の %load_ext autoreload と %autoreload 2 を使うと、実行のたびに自動で読み直されます（この拡張機能は手元では実行しておらず、IPython の公式ドキュメントで確認した内容です）。

まとめ

• import の書き方は import・from ... import・as・相対 import（. ..）の組み合わせ。迷ったら import モジュール名
• Python は sys.path を先頭から探す。ファイルを直接実行すると、先頭は「そのファイルのあるフォルダ」になる
• ModuleNotFoundError は、ルートのフォルダで python -m パッケージ.モジュール と実行するのが最初の一手
• 相対 import を含むファイルは直接実行せず、-m で実行する
• partially initialized module は循環 import の目印。import を関数の中へ移すか、共通部分を別ファイルに出す
• random.py など標準ライブラリと同じ名前は避ける。モジュール.__file__ で読み込み元を確認できる
• 外部ライブラリは python -m pip install で、実行する Python と同じ場所に入れる

株式会社RJCでは、Python の import やパッケージ構成の考え方を、仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。