Python モジュールとパッケージの基礎

JPKODA 編集部 May 8, 2026

Python 開発において、プロジェクトの複雑度が増すにつれ、すべてのコードを一つのファイルに詰め込むと、管理が非常に困難になります。モジュール (Modules) と パッケージ (Packages) は、コードを再利用可能で管理しやすい単位に整理するための仕組みを提供します。これらを利用することで、コードの再利用性が向上し、メンテナンス性が改善され、チームでの共同作業がよりスムーズになります。

本章では、モジュールとパッケージの基本概念を紹介し、それらがなぜ構造化された Python プログラムを書くための鍵となるのかを解説します。

1. モジュール（Modules）の理解

モジュールとは、本質的に Python の定義や文を含むファイルのことです。これらの定義には、関数、クラス、変数が含まれます。モジュールは、特定のツール（関数、クラス、変数）が入った「ツールボックス」のようなものであり、自分のプログラムからいつでも必要なツールを呼び出すことができます。

1.1 なぜモジュールを使用するのか？

コードの再利用性 (Code Reusability): モジュールを使用することで、同じコードを複数のプログラムで再利用でき、書き直す手間が省けます。
コードの構造化 (Organization): コードを論理的な単位に整理することで、理解しやすくメンテナンスしやすい状態に保てます。
名前空間管理 (Namespace Management): モジュールは独立した名前空間を作成するため、プログラムの異なる部分で変数名や関数名が衝突するのを防ぎます。
モジュール化 (Modularity): 巨大で複雑な問題を、より小さく管理しやすいサブ問題に分解する「モジュール化」の思想を促進します。

1.2 モジュールの作成

モジュールの作成は非常に簡単です。拡張子が .py の Python ファイルを保存するだけです。例えば、my_module.py という名前で以下の内容のファイルを作成してみましょう。

# my_module.py

def greet(name):
    """引数として渡された人に挨拶を表示する。"""
    print(f"こんにちは、{name}さん！")

def add(a, b):
    """2つの数値の和を返す。"""
    return a + b

my_variable = "これは my_module 内の変数です"

これで、このファイルは一つのモジュールとなり、他の Python プログラムからインポートして使用できるようになりました。

2. モジュールのインポート

モジュールで定義された内容を使用するには、プログラムにインポートする必要があります。Python ではいくつかのインポート方法が用意されています。

2.1 import 文

import 文はモジュール全体をインポートします。その後、ドット記法（モジュール名.定義名）を使用して、モジュール内部のリソースにアクセスします。

# main.py
import my_module

my_module.greet("Alice")  # 出力: こんにちは、Aliceさん！

result = my_module.add(5, 3)
print(result)  # 出力: 8

print(my_module.my_variable) # 出力: これは my_module 内の変数です

この例では、import my_module によって my_module.py ファイルが読み込まれます。

2.2 from ... import 文

from ... import 文を使用すると、モジュール内の特定の定義を現在の名前空間に直接インポートできます。この場合、ドット記法のプレフィックス（接頭辞）は不要になります。

# main.py
from my_module import greet, add, my_variable

greet("Bob")  # 出力: こんにちは、Bobさん！

result = add(10, 2)
print(result)  # 出力: 12

print(my_variable) # 出力: これは my_module 内の変数です

2.3 import ... as 文

import ... as 文を使用すると、異なる名称（エイリアス）でモジュールや特定の定義をインポートできます。これは、長いモジュール名を短縮したり、名前の衝突を避けたりする際に非常に便利です。

# main.py
import my_module as mm

mm.greet("Charlie")  # 出力: こんにちは、Charlieさん！

result = mm.add(7, 4)
print(result)  # 出力: 11

from my_module import add as addition

result = addition(10, 5)
print(result) # 出力: 15

3. モジュールの検索パス

モジュールをインポートするとき、Python は以下の特定のディレクトリ順序で検索を行います。

カレントディレクトリ（スクリプトを実行しているディレクトリ）。
環境変数 PYTHONPATH にリストされているディレクトリ（設定されている場合）。
インストールに関連するデフォルトのディレクトリ（通常は Python 標準ライブラリの場所）。

具体的な検索パスは、sys.path 変数を確認することで把握できます。

import sys
print(sys.path)

4. パッケージ（Packages）の理解

パッケージ（Package）とは、関連するモジュールをディレクトリ階層に整理する手法です。本質的には、複数のモジュールファイルと、特殊なファイルである __init__.py を含むディレクトリのことです。パッケージは、大規模なプロジェクトを論理的な単位に構造化し、管理しやすくするのに役立ちます。

4.1 なぜパッケージを使用するのか？

構造的な組織化 (Organization): モジュールを階層構造で整理できるため、関連するコードを見つけやすくなります。
名前空間管理 (Namespace Management): 階層的な名前空間を作成し、異なるパッケージ間でのモジュール名の衝突を防ぎます。
モジュール化 (Modularity): 大規模なプロジェクトを、より小さく管理しやすいサブプロジェクトに分割できます。

4.2 パッケージの作成

パッケージを作成するには、ディレクトリを作成し、その中に __init__.py ファイルを追加します。この __init__.py は空でも構いませんし、パッケージの初期化コードを含めることもできます。

典型的なパッケージ構造の例を以下に示します。

my_package/
├── __init__.py
├── module1.py
├── module2.py
└── subpackage/
    ├── __init__.py
    └── module3.py

4.3 パッケージからのインポート

階層関係を反映させた構文を使用して、パッケージからモジュールをインポートできます。

パッケージ内のモジュールを直接インポートする:

# main.py
import my_package.module1

my_package.module1.some_function()

from ... import をパッケージと組み合わせて使用する:

# main.py
from my_package import module2

module2.another_function()

サブパッケージからインポートする:

# main.py
from my_package.subpackage import module3

module3.yet_another_function()

4.4 init.py ファイルの役割

パッケージが最初にインポートされるとき、__init__.py ファイルが実行されます。主な用途は以下の通りです。

パッケージの状態の初期化。
パッケージレベルの変数や関数の定義。
特定のモジュールや定義をパッケージの公開名前空間にインポートする。

例えば、my_package/__init__.py に以下のコードを追加できます。

# my_package/__init__.py

from .module1 import some_function
from .module2 import another_function

__all__ = ['module1', 'module2', 'subpackage']

これにより、利用者は以下のように直接リソースにアクセスできるようになります。

# main.py
import my_package

my_package.some_function()
my_package.another_function()

__all__ 変数は、from my_package import * という構文が使われた際に、デフォルトでインポートされるモジュール名を定義するリストです。

5. 実践的なユースケース：ジオメトリライブラリの構築

幾何学（Geometry）ライブラリを構築する場合、以下のようにモジュールとパッケージを整理できます。

geometry/
├── __init__.py
├── shapes/
│   ├── __init__.py
│   ├── circle.py
│   └── rectangle.py
└── utils/
    ├── __init__.py
    └── math_utils.py

geometry ディレクトリがメインパッケージ。
shapes サブパッケージは、異なる形状を扱うモジュールを含みます。
utils サブパッケージは、ユーティリティモジュールを含みます。

以下は、geometry/shapes/circle.py 内のコード例です。

# geometry/shapes/circle.py
import math

def area(radius):
    """円の面積を計算する。"""
    return math.pi * radius**2

def circumference(radius):
    """円の周長を計算する。"""
    return 2 * math.pi * radius

このモジュールをメインプログラムで使用する方法は以下の通りです。

# main.py
from geometry.shapes import circle

radius = 5
circle_area = circle.area(radius)
circle_circumference = circle.circumference(radius)

print(f"円の面積: {circle_area}")
print(f"円の周長: {circle_circumference}")