Python 09：パッケージとフォルダ構成 ― フォルダを import すると何が起きるか

一言でいうと：パッケージは「目印の付いたフォルダ」

パッケージは、`__init__.py` というファイルが入ったフォルダです。__init__.py は「このフォルダは import できる部品のまとまりです」という目印で、中身は空でもかまいません。

パッケージの中の .py ファイルはサブモジュール、中のフォルダ（これも __init__.py 入り）はサブパッケージと呼びます。

import の名前に出てくる点（.）は、フォルダの区切り（/）です。import tenki.units.temp は、「tenki フォルダの中の、units フォルダの中の、temp.py」という道順を表しています。住所の「東京都・千代田区・丸の内」を、大きいほうから順に並べるのと同じです。

「パッケージ」という言葉には、もう1つ「pip で入れる配布物」という意味もあります（第11章）。この章で言うパッケージは、フォルダとしてのパッケージのほうです。混ざりやすいので、第10章で言葉を整理します。

tenki をパッケージにした、フォルダの実物

tenki を、図のようなフォルダの形にしました。

tenki-app/
├── main.py
└── tenki/
    ├── __init__.py
    ├── __main__.py
    ├── api.py
    ├── display.py
    └── units/
        ├── __init__.py
        └── temp.py

1つ気をつけたいのは、tenki-app（プロジェクトのフォルダ）と tenki（パッケージ）は別物だということです。import で使う名前は、内側の tenki です。外側の tenki-app は、第8章で見たとおり、main.py を起動したときに名簿（sys.path）の0段目になるフォルダです。その0段目の中に tenki/ があるので、import tenki で見つかります。

プロジェクトのフォルダ名は自由ですが、パッケージのフォルダ名は Python の名前として使える形（英小文字・数字・アンダースコア）にします。tenki-app のようなハイフン入りの名前は、import では書けません。

import a.b.c とフォルダは、1対1で対応する

点で区切った名前と、フォルダの道順は、そのまま対応します。

import tenki              # tenki/__init__.py
import tenki.api          # tenki/api.py
import tenki.units        # tenki/units/__init__.py
import tenki.units.temp   # tenki/units/temp.py

規則は2つだけです。

だから import tenki.api.fetch とは書けません。fetch は api.py の中の関数で、フォルダでもファイルでもないからです。関数を取り出すときは from tenki.api import fetch と書きます（第8章の from）。

JS と比べると、Node の require("./tenki/units/temp") の / が、Python では . になっていると考えるとわかりやすいでしょう。ただし、Python には ./ のような「ここから」の印がありません。import tenki.units.temp の最初の tenki は、名簿（sys.path）の中から探されます。探し方は第8章とまったく同じです。

import tenki.display ①：まず「tenki」を名簿で探す

main.py にはこう書いてあります。

# main.py
import tenki.display
tenki.display.show("Osaka")

この1行で何が起きるのかを、図のフォルダの木の上で1段ずつ追いかけます。黒い小包が「いま探しているもの・実行しているもの」、黄色がいま実行中のファイル、緑が実行済みのファイルです。番号の札は、実行された順番です。

公式ドキュメント（The import system）によると、import tenki.display は左の親から順に import します。

まず tenki です。第8章の手順どおり、棚（sys.modules）に無いので、名簿を上から探します。名簿の0段目は、main.py を起動した tenki-app です。そこに tenki/ というフォルダがあり、中に __init__.py がある。見つかりました。

ここまでは、tenki.py というファイルが見つかった第8章と同じです。違うのは、見つかったのがフォルダだということです。フォルダは実行できません。では、何が実行されるのでしょうか。

import tenki.display ②：tenki/__init__.py を上から実行

フォルダを import すると、その中の `__init__.py` が上から実行されます。__init__.py を実行した結果が、モジュール tenki の中身になります。

# tenki/__init__.py
print("tenki/__init__.py を実行")
from .api import fetch
__version__ = "0.1.0"

1行目の print が動き、出力に「tenki/__init__.py を実行」が出ました。これが1番目です。

続く2行目、from .api import fetch の .api は「同じパッケージの中の api」という意味です（相対 import。後でくわしく見ます）。つまり、tenki.api が必要になりました。

ここで Python は、__init__.py の実行を2行目でいったん止めて、先に tenki.api を import しに行きます。import は「その行を通ったときに実行される文」でした（第8章）。途中の import に出会ったら、そちらを済ませてから戻ってくる、という動きです。

関数の中で別の関数を呼ぶと、呼んだ先が終わってから続きに戻るのと同じです。

import tenki.display ③：途中で api.py が実行される

tenki.api は、tenki/ フォルダの中の api.py です。上から実行され、出力に「tenki/api.py を実行」が出ます。これが2番目です。

# tenki/api.py
print("tenki/api.py を実行")

def fetch(city):
    return {"city": city, "temp_c": 21}

ここで大事な点があります。api.py は、名簿（sys.path）を上から探し直して見つけたのではありません。

公式ドキュメントによると、パッケージは `__path__` という自分専用の小さな名簿を持っていて、サブモジュールはそこで探されます。tenki の __path__ は、tenki フォルダ1つだけが入ったリストです。

>>> import tenki
>>> tenki.__path__
['/Users/you/tenki-app/tenki']

だから、仮に名簿のどこか別の場所に api.py というファイルがあっても、tenki.api がそれと混ざることはありません。api.py が終わると、__init__.py の3行目に戻り、__version__ を作って最後まで実行し終わります。

import tenki.display ④：次に display.py

tenki の import が終わりました。次は点の右、tenki.display です。tenki の __path__（tenki フォルダ）の中で display.py が見つかり、上から実行されます。3番目です。

# tenki/display.py
print("tenki/display.py を実行")
from . import api
from .units import temp

def show(city):
    d = api.fetch(city)
    print(f"{d['city']}: {d['temp_c']}℃ / {temp.c_to_f(d['temp_c'])}℉")

2行目の from . import api を見てください。api は②③でもう実行済みで、棚（sys.modules）に tenki.api があります。だから api.py はもう一度実行されることはなく、棚から取り出して api という名前を付けるだけです（第8章：1回しか実行されない）。出力にも「tenki/api.py を実行」は2回目が出ていません。

3行目の from .units import temp では、tenki.units と tenki.units.temp がまだ棚にありません。そこで display.py の実行をまた止めて、units へ向かいます。

import tenki.display ⑤：units/ の __init__.py、そして temp.py

tenki.units.temp を使うには、左の親から順に、tenki → tenki.units → tenki.units.temp がすべて実行されている必要があります。tenki は済んでいるので、残りは2つです。

units もフォルダ（サブパッケージ）なので、まずその __init__.py が実行されます。この章では出力を見せるために print を1行だけ書いていますが、ふだんは空のファイルで十分です。

# tenki/units/temp.py
print("tenki/units/temp.py を実行")

def c_to_f(c):
    return c * 9 / 5 + 32

temp.py が終わると、止めていた display.py の3行目に戻り、temp という名前が付き、残りの def show が実行されて display.py が終わります。

このように、import は深さ優先で進みます。途中で出てきた import を先に最後まで片付け、終わったら元の場所に戻る。どれだけファイルが多くても、「出会った順に、1回ずつ」です。

import tenki.display ⑥：できあがり

main.py の import tenki.display の1行が終わりました。実際の出力の全体はこうです。

$ python3 main.py
tenki/__init__.py を実行
tenki/api.py を実行
tenki/display.py を実行
tenki/units/__init__.py を実行
tenki/units/temp.py を実行
Osaka: 21℃ / 69.8℉

最後の1行は、main.py の2行目 tenki.display.show("Osaka") の結果です。棚には tenki で始まるモジュールが5つ入りました。

__main__.py は実行されていません。これは python -m tenki と起動したときだけの入口です。

では、main.py に付いた名前は何でしょう。import tenki.display で付くのは、いちばん左の `tenki` だけです。display という名前は main.py にはありません（print(display) は NameError になります）。その代わり、サブモジュールを import すると、親のモジュールの中に子の名前が付けられる決まりがあるので、tenki.display とたどって届きます。

__init__.py の役目：パッケージの「表の顔」

__init__.py は目印であると同時に、`import tenki` したときの `tenki` そのものです。ここに書いた名前が、tenki.〇〇 として外から使えます。

tenki の __init__.py には from .api import fetch と書いてあるので、利用する側は tenki.api.fetch と奥まで書かなくても、tenki.fetch で使えます。実際に確かめると、2つは同じ関数です。

>>> import tenki
>>> tenki.fetch is tenki.api.fetch
True

この書き方は、ライブラリでとてもよく使われます。requests の __init__.py を開くと、実物にこう書いてあります。

# site-packages/requests/__init__.py（抜粋）
from .api import delete, get, head, options, patch, post, put, request
from .models import PreparedRequest, Request, Response
from .sessions import Session, session

requests.get(...) と書けるのは、get が requests/api.py に書かれていて、__init__.py がそれを表に並べているからです。JS で index.js から export { get } from "./api.js" と書き出すのと同じ役目です。

ただし、__init__.py は import のたびに必ず実行されるので、重い処理や print を置かないのが決まりです。この章の print は、順番を見せるための仕込みです。

相対 import：点1つは「同じパッケージ」、点2つは「1つ上」

パッケージの中のファイルどうしは、相対 import で互いを呼べます。

# tenki/display.py の中で
from . import api          # tenki.api
from .units import temp    # tenki.units.temp

# tenki/units/temp.py の中で
from .. import api         # tenki.api

点の数が、パッケージを上がる回数です。相対 import は from の形でしか書けません（import .api は文法エラー）。

基準になるのは「ファイルがディスクのどこにあるか」ではなく、「そのモジュールがどのパッケージに属しているか」です。モジュールには __package__ という名前が自動で入っていて、display.py なら 'tenki' です。. はこの 'tenki'、.. はその1つ上を指します。

もちろん、絶対の形 from tenki import api で書くこともできます。相対の形の良いところは、パッケージの名前を後で変えても中の import を直さなくてよいことです。どちらを使うかはプロジェクトでそろえれば十分です。

JS の "./api.js" は「このファイルのあるフォルダ」が基準でした。Python の . は「このモジュールのパッケージ」が基準です。ふだんは同じ場所を指しますが、この違いが次に見るエラーの原因になります。

パッケージの中のファイルを、直接実行するとエラー

display.py の動きを確かめたくて、直接実行してみます。

$ python3 tenki/display.py
Traceback (most recent call last):
  File "/Users/you/tenki-app/tenki/display.py", line 2, in <module>
    from . import api
ImportError: attempted relative import with no known parent package

「親のパッケージがわからないのに、相対 import しようとした」というエラーです。ファイルのパスを指定して直接実行すると、display.py はパッケージ tenki の一員ではなく、ただのスクリプト（`__main__`）として動きます。__package__ が空なので、. がどこを指すのか決まりません。

直すには、ファイルのパスではなく、モジュールの名前で起動します。

cd ~/tenki-app
python3 -m tenki.display

-m を付けると、Python は tenki.display という名前を名簿から探し、tenki パッケージを import したうえで display を実行します。実際に動かすと、__init__.py から順に実行され、エラーは出ません。

公式ドキュメントによると、-m で起動したときの名簿の0段目は、スクリプトのフォルダではなく今いるフォルダです。だから tenki-app に cd してから打つ必要があります。

python -m tenki と __main__.py

python3 -m tenki のように、パッケージを -m で起動すると、その中の `__main__.py` が実行されます。

# tenki/__main__.py
from tenki.display import show
show("Tokyo")

$ cd ~/tenki-app
$ python3 -m tenki
tenki/__init__.py を実行
tenki/api.py を実行
tenki/display.py を実行
tenki/units/__init__.py を実行
tenki/units/temp.py を実行
Tokyo: 21℃ / 69.8℉

__init__.py から順に実行され、最後に __main__.py が動いています。

第2章で出てきた python3 -m pip や python3 -m venv も、この仕組みです。pip も venv も、名簿のどこかにあるモジュール（パッケージ）で、-m はそれを名前で探して起動しています。「どの python の pip を動かすか」をはっきりさせられるので、pip より python3 -m pip が勧められるのでした。

第8章の if __name__ == "__main__": と役目は似ています。1ファイルのモジュールならその if、パッケージなら __main__.py が「起動されたときの入口」です。第14章では、これをさらに tenki というコマンドとして打てるようにします。

標準ライブラリの json も、同じ形のパッケージ

第8章で見つけた標準ライブラリの json を、もう一度開いてみます。

$ ls /Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/
__init__.py  __pycache__  decoder.py  encoder.py  scanner.py  tool.py

あなたの tenki/ と同じく、__init__.py と仲間の .py が並んでいるだけです。__init__.py の中にはこう書かれています。

# json/__init__.py（抜粋）
from .decoder import JSONDecoder, JSONDecodeError
from .encoder import JSONEncoder
import codecs

相対 import で仲間の decoder.py と encoder.py を読み、json.dumps や json.loads はこの __init__.py の中で定義されています。tenki と同じ書き方です。

REPL で __path__ と、サブモジュールの __file__ を見ると、実物の場所がわかります。

>>> import json
>>> json.__path__
['/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json']
>>> json.decoder.__file__
'/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py'

json.decoder と書くだけで届くのは、__init__.py が decoder を import した時点で、親の json の中に decoder という名前が付けられたからです（「できあがり」で見た決まり）。

pip で入れた requests も、同じ形のパッケージ

名簿の最後の段、site-packages に pip が置いた requests も見てみます。筆者の環境に入った requests 2.34.2 の中身です（__pycache__ と、型情報の目印 py.typed などは省いています）。

$ ls .venv/lib/python3.13/site-packages/requests/
__init__.py        __version__.py   _internal_utils.py  adapters.py
api.py             auth.py          certs.py            compat.py
cookies.py         exceptions.py    help.py             hooks.py
models.py          packages.py      sessions.py         status_codes.py
structures.py      utils.py

やはり __init__.py と .py の集まりです。requests.get の本体は api.py にあり、__init__.py が表に並べているのは前に見たとおりです。

これで、「ライブラリってどういう構造なの？」の答えの半分が出ました。ライブラリは、誰かが書いて配った、パッケージ（フォルダ）です。あなたの tenki/ と作りは同じで、エディタで開けば中身を読めます。特別な形式に変換された何かではありません。

残りの半分、「誰がどうやって配り、pip がどうやって置くのか」「フレームワークとは何が違うのか」は、第10章と第11章で見ていきます。

__init__.py が無いフォルダも import できてしまう

実は、__init__.py が無いフォルダも import できます。練習用のフォルダで試すと、エラーにならずにこう表示されます。

$ ls tools/
a.py
$ python3 -c "import tools, tools.a; print(tools)"
<module 'tools' (namespace) from ['/Users/you/practice/tools']>

(namespace) と出ています。これは名前空間パッケージという別の種類で、公式ドキュメントによると「1つのパッケージ名を、別々の場所にある複数のフォルダで分け合う」ための仕組みです。大きなライブラリが、同じ名前の下に別々の配布物を置くときなどに使われます。

「__init__.py は Python 3.3 から要らなくなった」という説明を見かけることがありますが、正確には「無くても別の種類として動くようになった」です。自分のコードでは、`__init__.py` を置いてふつうのパッケージにするのが素直です。置き忘れても動いてしまうので、気づかないうちに名前空間パッケージになっている、ということがあります。

よくある事故：別のフォルダのスクリプトから import できない

プロジェクトが育つと、便利なスクリプトを scripts/ のようなフォルダに置きたくなります。

# scripts/run.py
import tenki
print(tenki.fetch("Nagoya"))

ところが、tenki-app で実行するとこうなります（実際の出力です）。

$ python3 scripts/run.py
ModuleNotFoundError: No module named 'tenki'

tenki-app にいて、tenki/ はすぐ隣にあるのに見つかりません。原因は第8章の名簿です。名簿の0段目は「今いるフォルダ」ではなく「起動したスクリプトのあるフォルダ」でした。python3 scripts/run.py では0段目が tenki-app/scripts/ になり、tenki-app/ は名簿のどこにも入っていません。

-m で名前として起動すると、0段目が今いるフォルダになるので動きます。Node なら require("../tenki") と相対パスで書けば済む場面ですが、Python ではこうした「起動のしかた」が効いてきます。

sys.path.append("..") のように名簿を書き換えて逃げるコードも見かけますが、起動する場所が変わるとまた壊れます。根本的な解決は、tenki をインストールして site-packages から見えるようにすることです。それが次の src レイアウトの考え方です。

src レイアウト：パッケージを src/ の中に1段下げる

今よく勧められるのが、パッケージを src/ フォルダの中に置く src レイアウトです。uv で uv init --package --name tenki と打つと、最初からこの形で作られます（実際に作ったものです）。

tenki-app/
├── pyproject.toml
├── README.md
└── src/
    └── tenki/
        └── __init__.py

packaging.python.org の説明によると、この形の狙いは「開発中のコピーをうっかり import しない」ことです。tenki-app で何かを起動しても、0段目の tenki-app には tenki/ が無い（src/ の中にある）ので、名簿からは見えません。tenki を使うには、インストールする必要があります。すると、配る前の段階から「利用者が入れたときと同じ条件」で試せます。

でも、開発中に毎回インストールし直すのは面倒です。そこで、開発中は「実物はあっち」と書いた小さなファイルだけを site-packages に置きます。uv run は、これを自動でやってくれます。

$ uv run python -c 'import tenki; print(tenki.__file__)'
/Users/you/tenki-app/src/tenki/__init__.py
$ cat .venv/lib/python3.13/site-packages/tenki.pth
/Users/you/tenki-app/src

.pth は、起動時に site モジュールが読むファイルで、書かれたフォルダを名簿の最後に付け足します。これで src/ が名簿に入り、tenki が見つかります。この仕組み（編集可能インストール）は第14章でくわしく扱います。

JS と比べる：index.js と __init__.py

ここまでを、JS（Node）と並べます。

いちばん近いのは index.js と `__init__.py` です。どちらも「フォルダを1つの部品として読み込んだときの入口」で、よく使う物を表に並べる場所です。

違いもあります。Node の CommonJS では、require("./tenki") と書くと tenki/index.js が自動で探されますが、ESM ではフォルダ名だけの import が自動で index.js にはならず、ファイル名まで書く必要があります。Python の __init__.py は、どの書き方で import しても必ず実行されます。

もう1つは、自分のパッケージのいちばん上の名前（tenki）は、相対パスではなく名簿から探されることです。Node では自分のフォルダを ./ で指せますが、Python ではパッケージの外から tenki を指すには、tenki が名簿のどこかから見えている必要があります。「どこから起動するか」「インストールするか」が大事になるのはそのためです。

import でつまずいたときの原因の地図

パッケージが絡んだ import のエラーを、表にまとめます。どれも「名簿（sys.path・__path__）」「フォルダの形」「起動のしかた」のどれかに原因があります。

最後から2番目の循環 import は、深さ優先の動きを思い出すと理解できます。a.py の途中で b.py を import し、b.py が a を import すると、a はまだ途中までしか実行されていない（棚にはあるが、中身が揃っていない）ので、「途中までしか初期化されていないモジュールから、その名前は取れない」と言われます。

困ったときは、同じ python で次の3つを出すと、ほとんどの原因が見えます。

import sys
print(sys.path)            # 名簿
import tenki
print(tenki.__file__)      # 実際に見つかったファイル
print(tenki.__path__)      # パッケージの中の名簿