Portable Python Builder

Portable Python Builder は、インストール不要で持ち運べる Python 環境を作成する CLI ツールです。

astral-sh/python-build-standalone の install_only ビルドをベースに、Python 本体、必要な pip パッケージ、起動用スクリプトをまとめたフォルダまたは zip を生成します。生成した成果物は、配布先 PC に展開するだけで利用できます。

バイナリ名は ppb です。

目的

• 配布先 PC に Python をインストールせずに Python 環境を使いたい
• Windows / Linux / macOS 向けの Python 実行環境をビルド機で作りたい
• requests, pandas, fastapi などのライブラリを事前に同梱したい
• 社内配布やオフライン環境向けに、展開するだけで動く Python 環境を用意したい

特徴

• 対話式ウィザードでポータブル Python 環境を作成
• Python 3.9 から 3.14 系列の最新パッチを自動選択
• Wizard の表示言語を English / 日本語 から選択可能
• Windows / Linux / macOS 向け target を選択可能
• 用途別プリセットで追加ライブラリを簡単に選択
• pip パッケージを site-packages に事前インストール
• フォルダ出力または zip 出力を選択可能
• PBS アーカイブをローカルキャッシュして再利用
• 設定ファイル ppb.toml による再現可能なビルド

前提条件

• Rust / Cargo
• インターネット接続

依存パッケージの同梱には、ダウンロードした PBS Python 自身の pip を使用します。ホスト側の Python / pip は使用しません。

そのため、選択した target OS / CPU の Python がビルド機上で実行できる必要があります。例えば Linux 上で Windows target の Python を実行する構成は、そのままでは依存パッケージの事前インストールに失敗します。

インストール

cargo build --release

ビルド後の実行ファイル:

./target/release/ppb

開発中は cargo run -- でも実行できます。

cargo run -- --help

クイックスタート

対話式でポータブル Python 環境を作成します。

ppb wizard

ウィザードでは次の項目を順に選択します。

1. Language / 言語
2. Bundle name
3. Target platform
4. Python version line
5. Preset
6. Optional features
7. Additional packages
8. Output format

成功すると、標準では dist/ 配下に成果物が生成されます。

dist/
  Python/
    python/
    python.bat   # Windows target の場合
  Python.zip     # zip 出力を選んだ場合

Unix 系 target の場合、ランチャは拡張子なしの実行可能シェルスクリプトになります。

コマンド

ppb

短いコマンド案内を表示します。

ppb wizard [--output ppb.toml]

対話式で ppb.toml を生成し、ビルドを開始します。

ppb init [--output ppb.toml]

サンプル設定ファイルを生成します。既存ファイルは上書きしません。

ppb build [--config ppb.toml] [--no-cache]

設定ファイルからバンドルを作成します。

ppb list-releases [--limit 5]

python-build-standalone の最近のリリースを表示します。

Wizard のプリセット

ppb wizard では用途別プリセットを選択できます。

Preset	内容
Base	追加ライブラリなし
Automation	Excel、ファイル操作、Web取得、業務自動化
DataScience	CSV、数値解析、グラフ、軽い機械学習
WebServer	FastAPI、APIサーバ、ローカルWebアプリ
Custom	requirements.txt または直接入力

Optional features:

Feature	内容
Notebook	JupyterLab / Notebook
Streamlit	Streamlit アプリ
Measurement tools	進捗表示、リソース計測、リッチ表示
Dev tools	IPython、pytest、ruff
GUI tools	PySide6

設定ファイル

ppb.toml を直接編集してビルドすることもできます。

[bundle]
name = "Python"
output_dir = "./dist"

[python]
version = "3.12.7"
target = "x86_64-pc-windows-msvc"
release_tag = ""

[dependencies]
mode = "preinstall"
requirements = [
    "requests",
    "pandas",
]

[wrapper]
name = "python"

[archive]
format = "zip"

主な設定項目:

セクション	項目	説明
bundle	name	出力ディレクトリ名と zip 名
bundle	output_dir	成果物の出力先
python	version	CPython バージョン
python	target	配布先 target triple
python	release_tag	PBS リリースタグ。空なら最新
dependencies	mode	preinstall または wheelhouse
dependencies	requirements	同梱する pip パッケージ
dependencies	requirements_file	requirements ファイル
archive	format	zip または none

サポート対象 target:

• x86_64-pc-windows-msvc
• x86_64-unknown-linux-gnu
• aarch64-unknown-linux-gnu
• x86_64-apple-darwin
• aarch64-apple-darwin

キャッシュ

PBS アーカイブは次の優先順位でキャッシュ先を決定します。

1. PPB_CACHE_DIR
2. $HOME/.cache/ppb
3. ./.ppb-cache

キャッシュを無視して再ダウンロードする場合:

ppb build --no-cache

注意点

• 依存パッケージの同梱時は、ダウンロードした PBS Python 本体をビルド側で実行します。
• ホスト側の Python / pip は使用しません。
• target OS / CPU がビルド機で実行できない場合、依存パッケージの事前インストールはできません。
• 依存解決は pip に委譲します。
• sdist へのフォールバックは許可しません。
• 対象プラットフォーム向け wheel がないパッケージはビルドに失敗します。
• 既存の出力ディレクトリはビルド時に削除して再作成します。

開発

cargo fmt
cargo test
cargo run -- --help

設計メモ:

• 対話式 Portable Python 作成 CLI 設計