Pythonパッケージの自作入門。自分のコードをpip installできるようにする

Pythonを学んで自分なりの便利なツールが作れるようになると、次にぶつかる壁があります。 それは、他のプロジェクトでも同じ関数やクラスを使いたいとき、いちいちファイルをコピーするのが面倒だという悩みです。

あなたは、過去に書いた便利な関数を別のフォルダにコピーして使い回した経験はありませんか？

その作業を劇的に効率化し、プロのエンジニアへの一歩を踏み出す方法がパッケージ化です。

今回は、自作のプログラムをpip installできる形式にする方法を丁寧に解説します。 世界中のエンジニアが使っている仕組みを自分で作れるようになると、開発の楽しさが何倍にも膨らみます。

自作パッケージを作るメリットとは¶

なぜ、わざわざ自分のコードをパッケージにする必要があるのでしょうか？

単にファイルを置くだけでも動きますが、パッケージ化には代えがたい利点がいくつもあります。

まず大きなメリットは、プロジェクト間の依存関係をスッキリ整理できることです。 一度インストールしてしまえば、どのディレクトリからでもimport文一つで呼び出せるようになります。

また、エンジニアとしてのキャリアを考える上でも、パッケージ化の知識は欠かせません。 【関連記事】Pythonエンジニアとしての市場価値を上げる。 OSS活動をどうアピールすべきかでも触れていますが、自分のツールを公開することは大きな武器になります。

エンジニア歴10年の私から見ても、コードを再利用可能な形で管理できている人は、チーム開発での信頼度が非常に高いです。 「このツール、pipで入れられるようにしておいたよ」と言えるだけで、周囲からの評価はガラリと変わるでしょう。

準備編：パッケージのフォルダ構成を整える¶

パッケージを作る第一歩は、決まったルールに従ってフォルダを並べることです。 Pythonがパッケージとして認識するためには、特定のディレクトリ構造を守る必要があります。

ここでは、my_toolという名前のパッケージを作る想定で進めていきましょう。 まずは、デスクトップなどの作業場所に新しいフォルダを作成してください。

全体の構造は、以下の表のような形を目指します。 この構成は、現代のPython開発において最も推奨されている形式の一つです。

ファイル・フォルダ名	役割
my_package_project/	プロジェクト全体のルートフォルダです。
src/	ソースコードを格納する推奨される配置場所です。
src/my_tool/	実際にパッケージ名となるフォルダです。
src/my_tool/__init__.py	このフォルダがパッケージであることを示す重要なファイルです。
src/my_tool/main.py	あなたが書いたプログラム本体です。
pyproject.toml	パッケージの設定を書く、現代の標準的なファイルです。
README.md	ツールの使い方を説明するドキュメントです。

実際のフォルダ作成コマンドの例を見てみましょう。 ターミナルやコマンドプロンプトで、次のようにフォルダを準備します。

mkdir my_package_project
cd my_package_project
mkdir -p src/my_tool
touch src/my_tool/__init__.py
touch src/my_tool/main.py
touch pyproject.toml
touch README.md

ソースコードを書いてみよう¶

フォルダが準備できたら、実際に呼び出したいプログラムを書いていきます。 今回は、簡単な挨拶を返す関数をmain.pyに作成してみましょう。

# src/my_tool/main.py

def say_hello():
    return "こんにちは！自作パッケージの世界へようこそ。"

def add_numbers(a, b):
    return a + b

次に、外部からインポートしやすくするために__init__.pyを編集します。 このファイルに記述しておくことで、パッケージを読み込んだ際に直接関数を呼び出せるようになります。

# src/my_tool/__init__.py

from .main import say_hello, add_numbers

これで、コードの準備は完了です。 たったこれだけの作業で、あなたのコードはパッケージとしての形を成し始めました。

設定編：pyproject.tomlを作成する¶

2026年現在のPython開発において、最も重要なのがpyproject.tomlというファイルです。 以前はsetup.pyというファイルが主流でしたが、現在はこれが標準的な設定方法となっています。

このファイルには、ツールの名前やバージョン、制作者の情報などを記述します。 初心者のうちは難しく感じるかもしれませんが、書き方はほぼ決まっています。

以下の内容を、自分の環境に合わせて書き換えてみてください。

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

[project]
name = "my_tool"
version = "0.1.0"
authors = [
  { name="Your Name", email="yourname@example.com" },
]
description = "初めての自作パッケージです"
readme = "README.md"
requires-python = ">=3.8"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[tool.setuptools.packages.find]
where = ["src"]

この設定ファイルがあるおかげで、pipはあなたのコードをどうインストールすればいいかを理解します。

各項目の役割を簡単に整理しておきます。 基本的には、名前とバージョンさえ間違えなければ動作します。

項目名	説明
name	pip installする際の名前になります。他のパッケージと被らないようにしましょう。
version	プログラムを更新したら、ここを0.1.1などに上げていきます。
requires-python	動くPythonのバージョンを指定します。
dependencies	自分のツールが他のライブラリ（pandasなど）を使う場合に記述します。

以下の記事でpipについて詳しく解説しています。 【関連記事】Pythonのpipとは？Pythonのライブラリを管理するコマンド

実装編：自分のPCにインストールする¶

設定が終わったら、いよいよ自分のコードをシステムにインストールしてみましょう。 ここで使うのが、開発者にとって非常に便利な編集可能モード（Editable Mode）です。

通常、pipでインストールするとコードはPython専用のフォルダにコピーされてしまいます。 しかし、開発中はコードを書き換えるたびに再インストールするのは手間がかかります。

そこで、以下のコマンドを使います。 プロジェクトのルートフォルダ、つまりpyproject.tomlがある場所で実行してください。

pip install -e .

末尾の点は、現在のフォルダを指しています。 -eオプションを付けることで、ソースコードを編集すると即座にインストール済みのパッケージにも反映されるようになります。

成功したかどうか、確認してみましょう。 適当な場所でPythonを起動して、インポートを試してみます。

import my_tool
print(my_tool.say_hello())

こんにちは！自作パッケージの世界へようこそ。と表示されましたか？

パッケージ化で失敗しないためのコツ¶

ここで、私が長年の開発経験から学んだアドバイスを少しお話しさせてください。 パッケージ化は簡単ですが、長く運用していくためにはいくつかのコツがあります。

最も大切なのは、バージョニングを怠らないことです。 ちょっと直しただけだからとバージョンを変えずに放置すると、後でどれが最新か分からなくなります。

また、README.mdには必ず、何をするためのツールか、を一言書いておきましょう。 数ヶ月後の自分は、驚くほど自分が書いたコードの内容を忘れているものです。

さらに、コードの品質にも気を配る余裕が出てくると素晴らしいですね。 【関連記事】綺麗なコードって何？初心者から一歩抜け出す「リーダブルコード」の3つの基本を参考に、誰が見ても分かりやすいコードを目指しましょう。

私が初心者の頃は、何でも一つのファイルに詰め込みすぎてメンテナンス不能になったことがあります。 パッケージ化を機に、機能ごとにファイルを分ける癖をつけると、開発効率が劇的に向上します。

応用編：配布用のファイルを作る¶

自分のPCで動くようになったら、次は友人に渡したり、サーバーに置いたりしたくなりますよね。 そのために、パッケージを配布用ファイル、いわゆるWheel形式などに固める作業が必要です。

これにはbuildというツールを使います。 まずはbuildツール自体をインストールしましょう。

pip install build

インストールができたら、ビルドを実行します。 コマンドは非常にシンプルです。

python -m build

実行が終わると、dist/というフォルダの中に新しいファイルが出来上がります。 .whlという拡張子のファイルが、あなたのパッケージの完成体です。

このファイルをメールで送ったり、GitHubに置いたりすれば、他の人もインストール可能になります。 受け取った側は、以下のコマンドであなたのツールを使えるようになります。

pip install my_tool-0.1.0-py3-none-any.whl

自分がゼロから書いたコードが、公式のライブラリと同じように扱えるようになるのは感動的です。 配布の手軽さを知ることで、あなたのプログラミングの幅は一気に広がります。

よくあるトラブルと対処法¶

初めてのパッケージ化では、いくつか決まったエラーに遭遇することがあります。 焦らずに、一つずつチェックしていけば必ず解決できます。

よくあるのは、ModuleNotFoundErrorです。 これは、フォルダ構造が正しくないか、srcフォルダの設定がpyproject.tomlと一致していない場合に起こります。

また、インストールしたはずなのに古いコードが動くこともあります。 その場合は、一度アンインストールしてからやり直してみてください。

pip uninstall my_tool

キャッシュが残っていることが原因であれば、これで解決することが多いです。 トラブル時に確認すべきポイントを以下にまとめました。

• pyproject.tomlのファイル名が間違っていないか
• __init__.pyを空のままにしていないか、インポート設定を忘れていないか
• フォルダ名にハイフン「-」を使っていないか、アンダーバーを推奨します

特に、パッケージ名にはハイフンを使わないのがPythonの慣習です。 フォルダ名はmy_toolのように、アンダーバーで繋ぐのが最も安全な選択です。

Poetryの活用¶

今回は標準的な手法を紹介しましたが、実はもっと楽に管理できるツールもあります。 それがPoetry（ポエトリー）というツールです。

Poetryを使うと、ライブラリの追加やバージョンの管理がコマンド一つで行えます。 エンジニアの間では、今やデファクトスタンダードになりつつある強力な味方です。

【関連記事】Poetryとは？pipとの違いと使い方をやさしく解説で詳しく解説していますが、ステップアップしたい方はぜひ読んでみてください。 pyproject.tomlの手書きに慣れてきたら、Poetryに移行するのがスムーズな流れです。

モダンな開発環境を知ることは、AI時代のエンジニアにとって大きな差別化ポイントになります。 ツールに使われるのではなく、ツールを使いこなす側を目指していきましょう。

まとめ：あなたのコードを資産に変えよう¶

ここまで、Pythonパッケージを自作してインストールするまでの道のりを解説してきました。 最初は難しく感じたかもしれませんが、一度やってみると意外とシンプルですよね。

ただのスクリプトをパッケージに変えることは、あなたのコードを資産に変えることです。 再利用性が高まり、整理されたコードは、あなた自身の成長を助けてくれるでしょう。

今日作った小さなツールが、いつか世界中で使われるOSSになるかもしれません。 その第一歩を踏み出した自分を、ぜひ褒めてあげてください。

もし途中で分からなくなったら、何度でもこの記事に戻って確認してください。 Pythonの世界は広く、まだまだ楽しいことがたくさん待っています。

次はどんなツールを作って、パッケージにしてみたいですか？ あなたのアイディアが形になるのを、楽しみにしています。