0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@cake-milk

Python：モジュール・パッケージ・pip 早見表

0
Posted at

Python：モジュール・パッケージ・pip 早見表

Python 3.11以降を想定した、説明用・実務確認用の資料です。

目次

  1. 最初に押さえる全体像
  2. モジュールとは
  3. パッケージとは
  4. ビルトイン・標準ライブラリ・外部パッケージの違い
  5. importの基本
  6. 実行できるモジュール・パッケージ例
  7. pipとは
  8. pipでできることと主要コマンド
  9. pipでインストールしたものはどこにあるか
  10. よくあるエラーと確認手順
  11. まとめ

1. 最初に押さえる全体像

Pythonでは、処理を1つのファイルへ詰め込まず、モジュールやパッケージへ分割して再利用します。

1個の .py ファイル
    └─ モジュール

複数のモジュールをまとめた構成
    └─ パッケージ

配布・インストールできる形にまとめたプロジェクト
    └─ 配布パッケージ
          ↓ pipでインストール
       site-packages などへ配置

最重要：3種類の「パッケージ」を混同しない

用語 意味 例
Pythonパッケージ 複数のモジュールをまとめ、importできる構成 email、shop_tools
配布パッケージ pipなどで配布・インストールする単位 beautifulsoup4、Pillow
ライブラリ 再利用可能なコード群を指す一般用語 標準ライブラリ、外部ライブラリ

配布パッケージ名と、importする名前は一致しない場合があります。

python -m pip install beautifulsoup4

from bs4 import BeautifulSoup

python -m pip install Pillow

from PIL import Image

一言
pipがインストールする名前と、Pythonコードでimportする名前は、必ずしも同じではありません。

2. モジュールとは

定義

**モジュール（module／モジュール）**は、Pythonコードをまとめた再利用単位です。

通常は、1つの.pyファイルが1つのモジュールになります。

pricing.py
    ↓
pricingモジュール

# pricing.py

def calculate_total(price: int, quantity: int) -> int:
    """価格と数量から合計金額を返す。"""
    return price * quantity

別ファイルから読み込めます。

# main.py
import pricing

print(pricing.calculate_total(200, 3))

実行結果：

600

モジュールに入れられるもの

  • 変数
  • 定数
  • 関数
  • クラス
  • 例外クラス
  • 実行処理
  • ドックストリング

モジュールの種類

種類 説明 例
Pythonソースモジュール 通常の.pyファイル pricing.py
組み込みモジュール Python処理系へ組み込まれている sys、builtins
拡張モジュール Cなどで実装され、Pythonから読み込む 環境依存の.pyd、.so
パッケージ サブモジュールを持てるモジュール email、pathlibではなくemailなど

モジュールの情報を確認する

import json

print(json.__name__)
print(json.__package__)
print(json.__file__ is not None)

実行結果：

json
json
True

主な特殊属性：

属性 内容
__name__ モジュール名
__package__ 所属パッケージ名
__file__ 読み込まれたファイルのパス。ない場合もある
__doc__ モジュールのドックストリング
__spec__ インポート時の情報

組み込みモジュールには、通常のソースファイルがないため、__file__が存在しないことがあります。

3. パッケージとは

定義

**パッケージ（package／パッケージ）**は、モジュールやサブパッケージを階層化して管理する仕組みです。

一般的な通常パッケージでは、ディレクトリに__init__.pyを置きます。

sample_project/
├─ main.py
└─ shop_tools/
   ├─ __init__.py
   ├─ pricing.py
   └─ text.py
ファイル 役割
shop_tools/__init__.py shop_toolsを通常パッケージとして扱うためのファイル
shop_tools/pricing.py shop_tools.pricingモジュール
shop_tools/text.py shop_tools.textモジュール

__init__.pyの役割

  • 通常パッケージであることを明確にする
  • パッケージ読み込み時の初期化処理を書く
  • 外部へ公開する名前をまとめる
  • パッケージのドックストリングを書く

何も処理がなければ、空ファイルでも構いません。

# shop_tools/__init__.py
"""商品処理用のサンプルパッケージ。"""

from .pricing import calculate_total

__all__ = ["calculate_total"]

これにより、利用側を短くできます。

from shop_tools import calculate_total

print(calculate_total(200, 3))

名前空間パッケージ

Pythonには、__init__.pyを置かず、複数のディレクトリにまたがって構成できる名前空間パッケージもあります。

ただし、初学者向けの通常プロジェクトでは、まず次の構成を覚えれば十分です。

パッケージ用ディレクトリ
    ├─ __init__.py
    └─ モジュール.py

モジュールとパッケージの厳密な関係

Pythonのインポートシステム上、パッケージもモジュールの一種です。

  • すべてのパッケージはモジュール
  • すべてのモジュールがパッケージとは限らない
  • サブモジュールを持てるパッケージには__path__がある
import email
import json

print(hasattr(email, "__path__"))
print(hasattr(json, "__path__"))

実行結果：

True
False

一言
モジュールは主に1つのPythonファイル、パッケージは複数のモジュールを階層化して管理する仕組みです。

4. ビルトイン・標準ライブラリ・外部パッケージの違い

「ビルトイン」という言葉は、主に次の2つを指します。

4-1. 組み込み関数・組み込み型

**ビルトイン（built-in／ビルトイン）**の関数や型は、通常、importせずに使えます。

numbers = [10, 20, 30]

print(len(numbers))
print(sum(numbers))
print(type(numbers).__name__)

実行結果：

3
60
list

主な例：

  • 関数：print()、len()、sum()、range()、open()
  • 型：int、float、str、list、dict、tuple
  • 例外：ValueError、TypeError、KeyError
  • 定数：True、False、None

これらは、builtinsモジュールに定義されています。

import builtins

print(builtins.len([1, 2, 3]))
print(hasattr(builtins, "ValueError"))

実行結果：

3
True

4-2. 組み込みモジュール

Python処理系へ組み込まれているモジュールです。

import sys

print("sys" in sys.builtin_module_names)

CPythonでの一般的な実行結果：

True

組み込みモジュールは、importが必要な場合があります。

4-3. 標準ライブラリ

Python本体と一緒に提供されるライブラリです。

通常、別途pip installする必要はありませんが、利用時にはimportします。

from datetime import date
import json
from pathlib import Path

print(date(2030, 1, 2).isoformat())
print(json.dumps({"status": "ok"}, ensure_ascii=False))
print(Path("sample.txt").suffix)

実行結果：

2030-01-02
{"status": "ok"}
.txt

4-4. 外部ライブラリ・サードパーティパッケージ

Python本体とは別に開発・配布され、必要に応じてインストールするものです。

例：

  • Django
  • requests
  • selenium
  • pytest
  • mypy
  • ruff
python -m pip install requests

比較表

分類 import pip install 例
組み込み関数・型 原則不要 不要 len、str、list
組み込みモジュール 必要 不要 sys、builtins
標準ライブラリ 必要 原則不要 json、datetime、pathlib
外部パッケージ 必要 原則必要 requests、Django、selenium
自作モジュール 必要 同一プロジェクトなら不要 pricing.py

一言
ビルトインはすぐ使える機能、標準ライブラリはPythonに同梱された機能、外部パッケージは別途導入する機能です。

5. importの基本

モジュール全体を読み込む

import math

print(math.sqrt(81))

実行結果：

9.0

名前の所属が分かりやすい書き方です。

math.sqrt
└─ mathモジュールのsqrt関数

特定の名前を読み込む

from math import sqrt

print(sqrt(81))

実行結果：

9.0

別名を付ける

import datetime as dt

sample_date = dt.date(2030, 1, 2)
print(sample_date)

実行結果：

2030-01-02

パッケージ内から相対インポートする

# shop_tools/__init__.py
from .pricing import calculate_total

.は「現在のパッケージ」を表します。

書き方 意味
from .pricing import ... 同じパッケージのpricingから読み込む
from ..common import ... 1階層上のパッケージから読み込む

from module import *を避ける

from math import *  # 推奨しない

理由：

  • どの名前が追加されたか分かりにくい
  • 同名の変数や関数を上書きしやすい
  • 静的解析やコードレビューが難しくなる

Pythonがモジュールを探す場所

大まかなイメージは次のとおりです。

importを実行
  ↓
読み込み済みモジュールを確認
  ↓
組み込みモジュールを確認
  ↓
sys.pathに登録された場所を順に検索
  ↓
見つからなければModuleNotFoundError

検索対象を確認できます。

import sys

for path in sys.path:
    print(path)

出力されるパスは実行環境によって異なります。

6. 実行できるモジュール・パッケージ例

ディレクトリ構成

sample_project/
├─ main.py
└─ shop_tools/
   ├─ __init__.py
   └─ pricing.py

shop_tools/pricing.py 

"""金額計算を行うモジュール。"""

TAX_RATE = 0.10


def calculate_subtotal(price: int, quantity: int) -> int:
    """単価と数量から小計を返す。"""
    return price * quantity


def calculate_tax(subtotal: int) -> int:
    """小計から税額を返す。"""
    return int(subtotal * TAX_RATE)

shop_tools/__init__.py 

"""商品処理用のサンプルパッケージ。"""

from .pricing import calculate_subtotal, calculate_tax

__all__ = ["calculate_subtotal", "calculate_tax"]

main.py 

from shop_tools import calculate_subtotal, calculate_tax


def main() -> None:
    """サンプルの金額計算を実行する。"""
    subtotal = calculate_subtotal(price=200, quantity=3)
    tax = calculate_tax(subtotal)
    total = subtotal + tax

    print(f"小計: {subtotal}円")
    print(f"税額: {tax}円")
    print(f"合計: {total}円")


if __name__ == "__main__":
    main()

実行コマンド

sample_projectディレクトリで実行します。

python main.py

実行結果：

小計: 600円
税額: 60円
合計: 660円

-mでモジュールとして実行する

python -m main

実行結果：

小計: 600円
税額: 60円
合計: 660円

python -m package.moduleは、指定したモジュールをPythonのインポート規則に従って探し、実行します。

7. pipとは

**pip（ピップ）**は、Pythonの配布パッケージをインストール・更新・削除・確認するためのパッケージインストーラです。

主に、**PyPI（パイ・ピー・アイ／Python Package Index）**などのパッケージインデックスから取得します。

PyPIなど
  ↓ ダウンロード
pip
  ↓ インストール
現在選択しているPython環境のsite-packages

python -m pipを推奨する理由

python -m pip install requests

python -m pipは、先頭で指定したpythonに対応するpipを実行します。

python
  └─ このPython環境のpipを実行

単にpipと書くと、別のPythonへ紐づいたpipを実行する可能性があります。

バージョン確認

python -m pip --version

出力例：

pip 26.x from .../site-packages/pip (python 3.x)

確認ポイント：

  • pipのバージョン
  • pip本体の場所
  • 対象Pythonのバージョン

8. pipでできることと主要コマンド

8-1. インストール

python -m pip install requests

特定バージョン：

python -m pip install "requests==2.32.5"

バージョン範囲：

python -m pip install "requests>=2.32,<3"

ローカルプロジェクト：

python -m pip install .

開発中のプロジェクトを編集可能形式で導入：

python -m pip install -e .

8-2. 更新

python -m pip install --upgrade requests

pip自身を更新：

python -m pip install --upgrade pip

8-3. アンインストール

python -m pip uninstall requests

確認なしで実行する場合：

python -m pip uninstall -y requests

8-4. インストール済み一覧

python -m pip list

更新可能なものだけ確認：

python -m pip list --outdated

8-5. パッケージ詳細

python -m pip show requests

出力例：

Name: requests
Version: 2.32.5
Location: .../site-packages
Requires: certifi, charset_normalizer, idna, urllib3
Required-by:

複数ファイルの一覧も含める場合：

python -m pip show --files requests

8-6. 現在の環境をテキストへ出力

python -m pip freeze

ファイルへ保存：

python -m pip freeze > requirements.txt

別環境で再インストール：

python -m pip install -r requirements.txt

pip freezeは「現在インストールされているもの」を一覧化します。依存関係を新たに計算した厳密なロックファイルではありません。

8-7. 依存関係の整合性確認

python -m pip check

正常時の出力：

No broken requirements found.

8-8. インストールせずにダウンロード

python -m pip download requests -d downloaded_packages

オフライン環境へファイルを持ち込む場合などに使います。

8-9. Wheelを作成

**Wheel（ホイール）**は、Pythonのビルド済み配布形式です。

python -m pip wheel requests -w wheels

8-10. キャッシュ確認

python -m pip cache dir
python -m pip cache info
python -m pip cache list

キャッシュを全削除：

python -m pip cache purge

pipのキャッシュは、ダウンロード済みファイルなどの再利用場所です。実際のインストール先であるsite-packagesとは別です。

8-11. 設定確認

python -m pip config list
python -m pip config debug

8-12. 環境情報をJSONで確認

python -m pip inspect

**JSON（ジェイソン／JavaScript Object Notation）**形式で、環境内の配布パッケージ情報を出力します。

主要コマンド早見表

目的 コマンド
pip確認 python -m pip --version
インストール python -m pip install <名前>
更新 python -m pip install --upgrade <名前>
削除 python -m pip uninstall <名前>
一覧 python -m pip list
詳細 python -m pip show <名前>
環境一覧出力 python -m pip freeze
一括インストール python -m pip install -r requirements.txt
依存関係確認 python -m pip check
ダウンロードのみ python -m pip download <名前>
Wheel作成 python -m pip wheel <名前>
キャッシュ場所 python -m pip cache dir
設定確認 python -m pip config debug
JSON調査 python -m pip inspect

9. pipでインストールしたものはどこにあるか

基本：site-packages

Pythonの外部パッケージは、通常、対象環境のsite-packagesディレクトリへインストールされます。

仮想環境・Windowsの例

<project>\.venv\Lib\site-packages\

仮想環境・macOS/Linuxの例

<project>/.venv/lib/python3.x/site-packages/

実際の場所は、OS、Pythonの導入方法、仮想環境、--userの有無で変わります。

方法1：pip showで確認する

python -m pip show requests

Location:を確認します。

Location: .../site-packages

これは配布パッケージのインストール先を確認する方法です。

方法2：読み込まれたモジュールの__file__を確認する

python -c "import requests; print(requests.__file__)"

出力例：

.../site-packages/requests/__init__.py

これは、実際にimportされたモジュールのファイルを確認する方法です。

方法3：Pythonのサイトディレクトリを確認する

python -m site

または：

import site

print("環境のsite-packages:")
for path in site.getsitepackages():
    print(path)

print("ユーザー用site-packages:")
print(site.getusersitepackages())

出力される場所は環境によって異なります。

方法4：現在使っているPythonを確認する

python -c "import sys; print(sys.executable)"

出力例：

<project>/.venv/bin/python

Windowsでは次のような形式です。

<project>\.venv\Scripts\python.exe

方法5：検索パスを確認する

python -c "import sys; print(*sys.path, sep='\n')"

importは、主にこの検索パスを利用します。

配布パッケージの主な配置物

site-packages/
├─ requests/                  # importされるPythonパッケージ
├─ requests-2.32.5.dist-info/ # 配布パッケージのメタデータ
├─ urllib3/
└─ ...

実行コマンドは、次の場所へ作られることがあります。

環境 実行ファイルの主な場所
Windows仮想環境 .venv\Scripts\
macOS/Linux仮想環境 .venv/bin/

--userでインストールした場合

python -m pip install --user requests

ユーザー専用のsite-packagesへ入ります。

場所の確認：

python -m site --user-site

ただし、通常の仮想環境（venv）が有効な状態では、ユーザー専用のsite-packagesがPythonの検索対象に含まれないため、--userを指定するとエラーになります。

仮想環境を使用している場合は、--userを付けずに実行するのが基本です。

python -m pip install requests

この場合、パッケージは有効化している仮想環境内のsite-packagesへインストールされます。

「インストール済みなのにimportできない」場合

次の2つが同じ環境を指しているか確認します。

python -c "import sys; print(sys.executable)"
python -m pip --version

確認イメージ：

Python: <project>/.venv/bin/python
pip:    <project>/.venv/lib/python3.x/site-packages/pip

両方が同じ.venv配下なら、対応が取れています。

10. よくあるエラーと確認手順

ModuleNotFoundError 

ModuleNotFoundError: No module named 'requests'

主な原因：

  • 対象環境へインストールしていない
  • 別のPythonへインストールした
  • 配布パッケージ名とimport名を混同した
  • 自作モジュールの実行位置が不適切
  • ファイル名が標準ライブラリと衝突している

確認順：

python -c "import sys; print(sys.executable)"
python -m pip show requests
python -c "import requests; print(requests.__file__)"

pipコマンドが見つからない

'pip' is not recognized ...

まず次を試します。

python -m pip --version

Windowsでpythonが見つからない場合：

py -m pip --version

標準ライブラリと同じファイル名を付けた

次のようなファイル名は衝突の原因になります。

json.py
datetime.py
email.py
random.py

例えばjson.pyという自作ファイルがあると、標準ライブラリのjsonではなく、自作ファイルが先に読み込まれる場合があります。

確認：

import json

print(json.__file__)

依存関係が壊れている

python -m pip check

問題がある場合は、不足パッケージやバージョン不一致が表示されます。

グローバル環境へ入れてしまった

仮想環境を作成し直して、必要なものだけ入れます。

python -m venv .venv

仮想環境を有効化した後：

python -m pip install -r requirements.txt

11. まとめ

全体まとめ

Pythonのモジュールは、関数やクラスなどをまとめた再利用単位で、通常は1つの.pyファイルです。パッケージは、複数のモジュールやサブパッケージを階層化する仕組みです。組み込み関数や標準ライブラリはPythonに付属していますが、外部パッケージはpipでインストールします。pipで入れたものは、通常、現在使っているPython環境のsite-packagesに配置されます。

重要な流れ

処理を.pyファイルへ分ける
    ↓
モジュールとしてimportする
    ↓
複数モジュールをパッケージへまとめる
    ↓
外部パッケージが必要ならpython -m pip install
    ↓
pip show・__file__・sys.executableで環境を確認する

最低限覚えるコマンド

python -m pip --version
python -m pip install <配布パッケージ名>
python -m pip list
python -m pip show <配布パッケージ名>
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt
python -m pip check
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?