こんにちは！開発チームのリーダーをやっている先輩エンジニアです。
日々のコーディングで「お、この便利な処理、他のプロジェクトでも使い回したいな」とか「自分が作った最高のライブラリを、世界中のPythonエンジニアに使ってもらいたい！」と思ったことはありませんか？
昔のPython界隈では、`setup.py` を手書きし、`MANIFEST.in` でファイルを含め、`twine` コマンドでアップロードするという、なかなか泥臭くてミスしやすい儀式が必要でした。正直、パッケージの公開は「めんどくさい壁」として多くの開発者の前に立ちはだかっていたんです。
しかし、Poetryの登場でその世界は劇的に変わりました。
今回は、自作ライブラリをPyPI（Python Package Index）に美しく、そして完全に自動化されたワークフローで公開するための全手順を、シニアアーキテクトの視点から優しく、かつ深く解説していきます。これをマスターすれば、あなたのコードを世界へ届けるハードルはゼロになりますよ。それでは、一緒に見ていきましょう！
—
1. なぜ「Poetry」なのか？ パッケージ管理のパラダイムシフト
まず大前提として、なぜ `pip` や従来の `setuptools` ではなく、Poetryを使うのかという話を少しだけさせてください。
Poetryの本質は、「依存関係の解決（Dependency Resolution）」の美しさと、「プロジェクトのライフサイクル全体の統一」にあります。
- `pyproject.toml` による標準化: PEP 518/621で策定されたPythonのモダンな標準設定ファイル一つで、メタデータ、依存関係、ビルドシステムの設定をすべて管理できます。
- 堅牢なロックファイル (`poetry.lock`): チーム開発やCI/CD環境で「動かない」という悪夢を完全に排除します。
- シームレスなビルドと公開: 複雑なスクリプトを書くことなく、洗練されたCLIコマンド一発でパッケージングとパブリッシュが行えます。
つまり、Poetryは「書くことに集中したい開発者のための、最強のマネージャー」なのです。
—
2. 開発環境の準備とプロジェクトの初期化
それでは、実際に手を動かしながら進めていきましょう。まずはPoetryがインストールされていない場合は、公式推奨のインストーラーで導入します（ターミナルを開いてください）。
Poetryの公式インストーラーを実行（Linux/macOS用）
curl -sSL https://install.python-poetry.org | python3 –
インストールが完了したら、いよいよ自作ライブラリのプロジェクトを作成します。今回は `super-greeter` という、挨拶を少しだけリッチにするライブラリを作ると仮定しましょう。
新規プロジェクトのインタラクティブな作成
poetry new super-greeter
ディレクトリに移動
cd super-greeter
このコマンドを実行すると、以下のような美しいプロジェクトツリーが自動生成されます。
super-greeter/
├── README.md
├── pyproject.toml
├── super_greeter
│ └── __init__.py
└── tests
└── __init__.py
心臓部 `pyproject.toml` の最適化
生成された `pyproject.toml` をエディタで開いてみてください。ここがあなたのライブラリの「戸籍」になります。PyPIに公開するために、必要なメタデータを書き換えましょう。
[tool.poetry]
ライブラリのユニークな名前（PyPIで重複していないもの）
name = “super-greeter-yourname”
初期バージョン
version = “0.1.0”
ライブラリの簡単な説明
description = “A modern, delightful greeting library for Python.”
作者名とメールアドレス
authors = [“Your Name
READMEファイルの指定（PyPIのトップページに表示されます）
readme = “README.md”
パッケージが属するカテゴリや検索タグ
classifiers = [
“Programming Language :: Python :: 3”,
“License :: OSI Approved :: MIT License”,
“Operating System :: OS Independent”,
]
[tool.poetry.dependencies]
実行時に必要な依存関係（例としてPython3.8以上を指定）
python = “^3.8”
[tool.poetry.group.dev.dependencies]
開発・テスト時のみ必要な依存関係
pytest = “^7.0.0”
[build-system]
ビルドバックエンドとしてPoetryを使用することを宣言
requires = [“poetry-core”]
build-backend = “poetry.core.masonry.api”
> 先輩からのワンポイントアドバイス: `name` フィールドはPyPI全体で一意である必要があります。すでに他の人に使われている名前だと公開時にエラーになるため、独自性を出すために名前にプレフィックス（自分の名前や組織名）を付けるのが実務のテクニックです。
—
3. 「Hello World」：ライブラリのコードを書く
公開する中身を実装しましょう。`super_greeter/super_greeter.py`（新規作成）に、シンプルな関数を定義します。
super_greeter/super_greeter.py
def greet(name: str) -> str:
“””
指定された名前に向けて、リッチな挨拶メッセージを返す関数
“””
return f”Hello, {name}! Welcome to the world of modern Python packaging.”
そして、それを外部からインポートできるように `super_greeter/__init__.py` を編集します。
super_greeter/__init__.py
パッケージのトップレベルから直接呼び出せるように公開APIを定義
from .super_greeter import greet
__version__ = “0.1.0”
テストも書いておきしょう。`tests/test_super_greeter.py` を作成します。
tests/test_super_greeter.py
from super_greeter import greet
def test_greet():
assert greet(“Architect”) == “Hello, Architect! Welcome to the world of modern Python packaging.”
ターミナルで `poetry run pytest` を実行し、テストが緑色でパスすることを確認してください。この「綺麗に動く」という確信こそが、クリーンな開発の第一歩です。
—
4. Poetryによるビルド（`build` コマンドの内部挙動）
コードの準備ができたら、いよいよPyPIにアップロードするための「成果物」を作ります。ここで登場するのが `poetry build` です。
poetry build
このコマンドを実行すると、プロジェクト内に `dist/` というディレクトリが作られ、その中に以下の2つのファイルが生成されます。
1. `sdist`（ソース配布物 / `.tar.gz`）:
Pythonのソースコードそのものと、設定ファイルを含んだアーカイブ。ユーザーがソースからビルドする場合に使われます。
2. `wheel`（ビルト配布物 / `.whl`）:
現代の標準であるバイナリパッケージ形式。コンパイル済みの状態に近いため、`pip install` した際に爆速でインストールが完了します。
> 裏側のメカニズム: Poetryは内部で `pyproject.toml` の `[build-system]` セクションを読み込み、`poetry-core` という高速なビルダーを使って、PEP 517に完全準拠した安全なパッケージをミリ秒単位で生成しています。手動で `setup.py sdist bdist_wheel` を叩いていた暗黒時代とはおさらばです。
—
5. PyPIへの公開とセキュアな認証フロー
ビルドした成果物をいよいよ世界へ公開（パブリッシュ）します。
事前準備：PyPIアカウントの作成とAPIトークンの発行
セキュリティの観点から、PyPIへの公開にはパスワードではなくAPIトークンを使用するのが現代の常識です。
1. [PyPI（本番環境）](https://pypi.org/) または [TestPyPI（テスト環境・推奨）](https://test.pypi.org/) にアカウントを作成します。
2. アカウント設定画面から API tokens を生成し、トークン文字列（`pypi-…` で始まる文字列）をコピーします。
Poetryへの認証情報の設定
コピーしたトークンを、Poetryに教えます。
本番PyPIのトークンを設定する場合
poetry config pypi-token.pypi さんのAPIトークンをここに貼り付け
テスト環境（TestPyPI）を使う場合（※初めての公開時はこちらを強く推奨！）
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry config pypi-token.testpypi テスト用APIトークンをここに貼り付け
> なぜTestPyPIを使うべきなのか？
> 本番PyPIは、一度バージョンを公開すると、原則として同じバージョンを二度と上書きアップロードできません（タイポやミスがあってもバージョンを上げる必要があります）。そのため、まずはTestPyPIで公開フローが成功するかテストするのが、プロのエンジニアの流儀です。
いざ、パブリッシュ！
準備が整ったら、以下のコマンドで公開を実行します。
TestPyPIに公開する場合
poetry publish -r testpypi
本番PyPIに公開する場合
poetry publish
ターミナルに「Uploading… 100%」という表示が出て成功すれば、あなたの作ったライブラリは無事に世界中のエンジニアからインストール可能な状態になりました！
確認として、別のディレクトリに移動して実際にインストールできるか試してみてください。
TestPyPIからインストールする場合の例
pip install –index-url https://test.pypi.org/simple/ super-greeter-yourname
—
6. バージョン管理のルール（セマンティックバージョニング）
パッケージのアップデートを続ける際、バージョン番号の付け方には厳格なルールがあります。これがセマンティックバージョニング（SemVer: `MAJOR.MINOR.PATCH`）です。
- `PATCH` (例: 0.1.0 -> 0.1.1): バグ修正。下位互換性を完全に保った修正。
- `MINOR` (例: 0.1.0 -> 0.2.0): 新機能の追加。既存の機能を壊さない（下位互換性を保った）機能追加。
- `MAJOR` (例: 0.1.0 -> 1.0.0): 破壊的変更。過去のバージョンと互換性のない仕様変更を行う場合。
Poetryでは、このバージョン変更もコマンド一つで行えます。
パッチバージョンを自動で上げる（0.1.0 -> 0.1.1）
poetry version patch
マイナーバージョンを上げる（0.1.0 -> 0.2.0）
poetry version minor
このコマンドを実行すると、自動的に `pyproject.toml` や `__init__.py` のバージョン番号を書き換えてくれます。マジで便利ですよね。
—
7. 【総仕上げ】GitHub Actionsによる完全自動化ワークフロー
さて、ここまで手動でのビルドと公開を見てきましたが、実務において手動で `poetry publish` を叩くのはヒューマンエラーの元です。
「GitHubの `main` ブランチにタグ（例: `v0.1.0`）をプッシュしたら、自動でテストが走り、自動でPyPIに公開される」というCI/CDパイプラインを構築しましょう。
プロジェクトのルートに `.github/workflows/deploy.yml` を作成し、以下の設定を記述します。
name: Publish to PyPI
mainブランチに対して v (例: v1.0.0) のタグがプッシュされたときに起動
on:
push:
tags:
- ‘v’
jobs:
deploy:
name: Build and publish to PyPI
runs-on: ubuntu-latest
steps:
# 1. リポジトリのコードをチェックアウト
- name: Checkout code
uses: actions/checkout@v4
# 2. Python環境のセットアップ
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: ‘3.11’
# 3. Poetryのインストール
- name: Install Poetry
uses: snok/install-poetry@v1
with:
version: 1.8.2
virtualenvs-create: true
virtualenvs-in-project: true
# 4. 依存関係のインストールとテストの実行
- name: Run Tests
run: |
poetry install
poetry run pytest
# 5. Poetryでパッケージをビルド
- name: Build package
run: poetry build
# 6. PyPIへ自動パブリッシュ（GitHub Secretsのトークンを使用）
- name: Publish to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
with:
password: ${{ secrets.PYPI_API_TOKEN }}
GitHub側の設定
1. GitHubの該当リポジトリの Settings > Secrets and variables > Actions に移動します。
2. `New repository secret` をクリックし、名前を `PYPI_API_TOKEN`、値にあなたのPyPI APIトークンを貼り付けて保存します。
これで完了です！あとはコードを修正し、以下のようにGitタグを切ってプッシュするだけ。
git tag v0.1.1
git push origin v0.1.1
たったこれだけで、GitHubが自動的にテストを行い、PyPIへあなたのライブラリを届けてくれます。あなたが寝ている間にも、世界中の誰かがあなたのコードを使えるようになるのです。
—
おわりに
今回は、Poetryを使った自作ライブラリの作成からPyPI公開、そしてGitHub Actionsによる自動化までのワークフローを解説しました。
最初は覚えることが多く感じるかもしれませんが、`pyproject.toml` を軸としたこのモダンな開発スタイルに慣れると、もう古い開発手法には戻れなくなります。
「自分が書いたコードが、誰かの役に立つ」。パッケージの公開は、エンジニアにとって最高のご褒美であり、スキルアップの大きなマイルストーンです。
ぜひ今回の記事を参考に、あなたの最高傑作をPyPIに羽ばたかせてみてくださいね。応援しています！