4. Windows で Python を使う
***************************

このドキュメントは、 Python を Microsoft Windows で使うときに知ってお
くべき、 Windows 固有の動作についての概要を伝えることを目的としていま
す。

多くの Unix システムやサービスと異なり、Windows にはシステムでサポート
される Python のインストールが含まれていません。 その代わり、Python は
CPython チームを含むさまざまな配布元から入手できます。 Python の各ディ
ストリビューションにはそれぞれ長所と短所がありますが、一般に、使用して
いるほかのツールと一貫して使えることは大きな利点です。 ここで説明する
手順に進む前に、既存のツールから Python を直接入手できるか調べることを
お勧めします。

CPython チームが提供する Python を入手するには、Python インストールマ
ネージャを使ってください。 これは、Windows マシン上で Python をグロー
バルなコマンドとして使えるようにし、システムと連携して、継続的な更新を
サポートする独立したツールです。 Python インストールマネージャは
python.org/downloads または Microsoft Store app からダウンロードできま
す。

Python インストールマネージャをインストールすると、どのターミナルから
でもグローバルな "python" コマンドを使って、現在インストールされている
最新バージョンの Python を起動できます。 バージョンを追加したり削除し
たりすると、このバージョンが変わることがあります。 "py list" コマンド
で、現在使われるバージョンを確認できます。

一般に、プロジェクトごとに 仮想環境 を作成し、ターミナルで
"<env>\Scripts\Activate" を実行して使うことをお勧めします。 これにより
、プロジェクト同士を分離し、時間が経っても一貫した環境を保ち、パッケー
ジが追加したコマンドもセッション内で使えるようにできます。 仮想環境は
"python -m venv <env path>" で作成してください。

"python" や "py" コマンドが動作していないようであれば、後述の トラブル
シューティング の節を参照してください。 PC の設定に、追加の手作業が必
要な場合もあります。

Python インストールマネージャを使う以外に、Python を NuGet パッケージ
として入手することもできます。 これらのパッケージの詳細については、後
述の nuget.org パッケージ を参照してください。

埋め込み用ディストリビューションは、より大きなアプリケーションに埋め込
むのに適した、Python の最小限のパッケージです。 Python インストールマ
ネージャを使ってインストールできます。 これらのパッケージの詳細につい
ては、後述の 埋め込み可能なパッケージ を参照してください。


4.1. Python インストールマネージャ
==================================


4.1.1. インストール
-------------------

The Python install manager can be installed from the Microsoft Store
app or downloaded and installed from python.org/downloads. The two
versions are identical.

Store からインストールするには、"Install" をクリックするだけです。 完
了したら、ターミナルを開いて "python" と入力すると使い始められます。

python.org からダウンロードしたファイルをインストールするには、ダブル
クリックして "Install" を選択するか、Windows PowerShell で "Add-
AppxPackage <path to MSIX>" を実行してください。

インストール後は、"python"、"py"、"pymanager" コマンドが使えるはずです
。 既に Python がインストールされていたり、"PATH" 変数を変更していたり
する場合は、それらを削除するか、変更を元に戻す必要があるかもしれません
。 動作しないコマンドへの対処については、トラブルシューティング を参照
してください。

初めてランタイムをインストールすると、ディレクトリを "PATH" に追加する
よう求められることがあります。 "py" コマンドを使いたい場合は任意ですが
、"python3.15.exe" などのすべてのエイリアスを使いたい人のために、この
選択肢が用意されています。 このディレクトリはデフォルトでは
"%LocalAppData%\Python\bin" ですが、管理者が変更することもできます。
パスを追加するためのシステム設定ページを開くには、スタートをクリックし
、"Edit environment variables for your account" を検索してください。

インストールした Python ランタイムには、それぞれ専用のスクリプト用ディ
レクトリがあります。 スクリプトを使いたい場合は、これらも "PATH" に追
加する必要があります。

Python インストールマネージャは新しいリリースに自動的に更新されます。
これは、インストール済みの Python ランタイムには影響しません。 Python
インストールマネージャをアンインストールしても、Python ランタイムはア
ンインストールされません。

たとえば、MSIX に対応していない自動展開ソフトウェアを使っている場合や
、Windows Server 2019 を対象にしている場合など、利用環境で MSIX をイン
ストールできないときは、後述の 高度なインストール を参照してください。


4.1.2. 基本的な使い方
---------------------

Python の起動には "python" コマンドを推奨します。 このコマンドは、起動
するスクリプトが要求するバージョン、アクティブな仮想環境、またはインス
トール済みのデフォルトのバージョンを起動します。 別途設定しない限り、
デフォルトは最新の安定版です。 バージョンが明示的に要求されておらず、
ランタイムがまったくインストールされていない場合は、現在の最新リリース
が自動的にインストールされます。

複数のランタイムバージョンを扱う場合は、どの場面でも "py" コマンドを推
奨します。 "python" や従来の "py.exe" ランチャの代わりに、どこでも使え
ます。 デフォルトでは "py" は "python" と同じように動作しますが、コマ
ンドラインオプションで特定のバージョンを選択したり、サブコマンドでイン
ストールを管理したりすることもできます。 これらについては後述します。

"py" コマンドは以前のバージョンで既に使われている可能性があるため、曖
昧さのない "pymanager" コマンドも用意されています。 Python インストー
ルマネージャを使うことを意図したインストールスクリプトでは、既存のイン
ストールと衝突する可能性が低い "pymanager" の使用を検討してください。
両コマンドの違いは、引数を渡さずに実行したときだけです。 "py" はデフォ
ルトのインタープリタを起動し、"pymanager" はヘルプを表示します
("pymanager exec ..." は "py ..." と同じ動作をします)。

これらのコマンドには、コンソールウィンドウを作成しないウィンドウ版もそ
れぞれあります。 "pyw"、"pythonw"、"pywmanager" です。 "python" コマン
ドと同様に動作する "python3" コマンドも含まれています。 これは、一般的
な POSIX のコマンドを Windows 上で誤って使ってしまう場合に対応するため
のもので、広く使ったり推奨したりすることは意図していません。

デフォルトのランタイムを起動するには、ランタイムに渡したい引数 (スクリ
プトファイルや起動するモジュールなど) を付けて "python" または "py" を
実行してください:

   $> py
   ...
   $> python my-script.py
   ...
   $> py -m this
   ...

デフォルトのランタイムは、環境変数 "PYTHON_MANAGER_DEFAULT" または設定
ファイルで上書きできます。 設定の詳細については、設定 を参照してくださ
い。

特定のランタイムを起動するため、"py" コマンドは "-V:<TAG>" オプション
を受け付けます。 このオプションは、ほかのすべてのオプションより先に指
定しなければなりません。 タグはランタイムの識別子の一部または全体です
。 CPython チームが提供するランタイムではバージョンのような形で、プラ
ットフォームが付くこともあります。 互換性のため、タグが公式リリースを
指していて "3" で始まる場合は、"V:" を省略できます。

   $> py -V:3.15 ...
   $> py -V:3-arm64 ...

ほかの配布元のランタイムでは、*company* も含める必要があるかもしれませ
ん。 タグとの間はスラッシュ ("/" または "\") で区切り、完全な値の任意
の接頭辞まで短縮できます。 company が "PythonCore" の場合は指定を省略
でき、特定の company の最新リリースを使いたい場合はタグの指定を省略で
きます (ただしスラッシュは省略できません)。

   $> py -V:Distributor\1.0 ...
   $> py -V:distrib/ ...

バージョンが指定されておらず、スクリプトファイルが渡された場合、スクリ
プトに *シェバン行* があるか調べます。 これはファイルの先頭行に記述す
る特別な形式で、コマンドを上書きできます。 詳しくは シェバン行 を参照
してください。 シェバン行がない場合や解決できない場合は、デフォルトの
ランタイムでスクリプトを起動します。

アクティブな仮想環境で実行していて、特定のバージョンを要求しておらず、
シェバン行もない場合、デフォルトのランタイムはその仮想環境になります。
この場合、"python" コマンドは既に上書きされていて、これらの確認は行わ
れないことが多いでしょう。 ただし、この動作によって "py" コマンドも同
じように使えます。

ランタイムがまったくインストールされていない場合、どの起動コマンドも要
求されたバージョンをインストールして起動しようとします。 ただし、いず
れかのバージョンがインストールされた後は、要求されたバージョンがないと
きにインストールを行うのは "py exec ..." と "pymanager exec ..." コマ
ンドだけです。 それ以外の形式のコマンドはエラーを表示し、先に "py
install" を使うよう案内します。


4.1.3. コマンドのヘルプ
-----------------------

"py help" コマンドは、サポートされているすべてのコマンドとそのオプショ
ンを表示します。 どのコマンドでも、"-?" オプションを渡すか、"py help"
にそのコマンド名を渡すとヘルプを表示できます。

   $> py help
   $> py help install
   $> py install /?

すべてのコマンドで、"py help" に表示される共通のオプションを使えます。
これらのオプションはサブコマンドの後に指定しなければなりません。 "-v"
または "--verbose" を指定すると出力が増え、"-vv" を指定するとデバッグ
用にさらに増えます。 "-q" または "--quiet" を渡すと出力が減り、"-qq"
を渡すとさらに減ります。

"--config=<PATH>" オプションでは、複数の設定をまとめて上書きする設定フ
ァイルを指定できます。 これらのファイルの詳細については、後述の 設定
を参照してください。


4.1.4. ランタイムの一覧表示
---------------------------

   $> py list [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...]

"py list" を使うと、インストール済みのランタイムの一覧を表示できます。
1 つ以上のタグ (company の指定は任意) をフィルタとして追加でき、それぞ
れに接頭辞 "<"、"<="、">="、">" を付けて範囲を制限できます。

さまざまな形式をサポートしており、"--format=<FMT>" または "-f <FMT>"
オプションで渡せます。 形式には "table" (見やすい表形式)、"csv" (カン
マ区切りの表)、"json" (単一の JSON データ)、"jsonl" (結果ごとに 1 つの
JSON データ)、"exe" (実行ファイルのパスのみ)、"prefix" (インストール先
のパスのみ) があります。

"--one" または "-1" オプションは、結果を 1 つだけ表示します。 デフォル
トのランタイムが含まれている場合は、それを表示します。 そうでなければ
、"最良" の結果を表示します ("最良" の定義は意図的に曖昧にしていますが
、通常は最新のバージョンです)。 "py list --one <TAG>" が表示する結果は
、"py -V:<TAG>" が起動するランタイムと一致します。

"--only-managed" オプションは、Python インストールマネージャでインスト
ールされていないランタイムを結果から除外します。 これは、"py" コマンド
で更新やアンインストールができるランタイムを調べるときに役立ちます。

"--online" オプションは、デフォルトの取得元を指定して "--source=<URL>"
を渡すための短縮形です。 どちらかのオプションを渡すと、オンラインイン
デックスでインストール可能なランタイムを検索します。 "py list --online
--one <TAG>" が表示する結果は、"py install <TAG>" がインストールするラ
ンタイムと一致します。

   $> py list --online 3.15

旧ランチャとの互換性のため、"--list"、"--list-paths"、"-0"、"-0p" コマ
ンド (たとえば "py -0p") も残されています。 これらは追加のオプションを
受け付けず、従来の形式で出力します。


4.1.5. ランタイムのインストール
-------------------------------

   $> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]

"py install" を使うと、新しいバージョンのランタイムを追加できます。 1
つ以上のタグを指定でき、特別なタグ "default" でデフォルトを選択できま
す。 インストールでは範囲指定をサポートしていません。

CPython は複数の種類のランタイムを公開しています。 ほとんどのユーザに
は、標準の CPython ランタイムを提供する "PythonCore" を推奨します。 接
頭辞のないタグは "PythonCore\<TAG>" として扱われます。

"PythonTest" には、標準のランタイムに加えてテストスイートとデバッグシ
ンボルが含まれています。 Python のテストやデバッグのためにこれらの追加
ファイルを必要とする、貢献者やユーザ向けのものです。

"PythonEmbed" provides a minimal embeddable distribution for
applications that bundle Python rather than for interactive use. It
would normally be used with the "--target" option described below.

利用可能なランタイムの種類を表示するには、次を実行してください。

   py list --online

特定の種類をインストールするには、"py install" に渡すタグにその種類を
含めてください:

   py install PythonTest\3.15

"--source=<URL>" オプションでは、ランタイムの取得に使うオンラインイン
デックスを上書きできます。 オフラインでのインストール に示すように、オ
フラインインデックスにも使えます。

"--force" を渡すと、キャッシュされたファイルをすべて無視し、既存のイン
ストールを削除して、指定されたものに置き換えます。

Passing "--update" will replace existing installs if the new version
is newer. Otherwise, they will be left. If no tags are provided with "
--update", all installs managed by the Python install manager will be
updated if newer versions are available. Updates will remove any
modifications made to the install, including globally installed
packages, but will leave "site-packages" and "Scripts" directories as
is.  Virtual environments are also unaffected.

"--dry-run" を渡すと、出力とログを生成しますが、インストールは一切変更
しません。

"--refresh" を渡すと、インストール済みランタイムのすべての登録を更新し
ます。 これにより、スタートメニューのショートカット、レジストリキー、
グローバルなエイリアス ("python3.15.exe" やインストール済みスクリプト
のものなど) を再作成します。 これらはランタイムのインストール時に自動
的に更新されますが、パッケージのインストール後には手動での更新が必要な
場合があります。

上記のオプションに加えて、"--target" オプションを使うと、通常のインス
トールを行う代わりに、指定したディレクトリにランタイムを展開します。
これは、より大きなアプリケーションにランタイムを埋め込むときに役立ちま
す。 通常のインストールとは異なり、"py" は展開されたランタイムを認識せ
ず、スタートメニューなどのショートカットも作成されません。 ランタイム
を起動するには、展開先ディレクトリにあるメインの実行ファイル (通常は
"python.exe") を直接実行してください。

   $> py install ... [-t=|--target=<PATH>] <TAG>

"py exec" コマンドは、要求されたランタイムがまだなければインストールし
ます。 この動作は "automatic_install" 設定
("PYTHON_MANAGER_AUTOMATIC_INSTALL") で制御し、デフォルトでは有効です
。 利用可能なランタイムがまったくない場合は、設定で許可されていれば、
どの起動コマンドも自動インストールを行います。 これは新しいユーザが使
い始めやすくするためのものですが、通常はこれに頼らず、"py exec" コマン
ドや明示的なインストールコマンドを使ってください。


4.1.6. オフラインでのインストール
---------------------------------

Python をオフラインでインストールするには、まずネットワークにアクセス
できるマシン上でオフラインインデックスを作成する必要があります。

   $> py install --download=<PATH> ... <TAG>...

"--download=<PATH>" オプションは、列挙したタグのパッケージをダウンロー
ドし、それらのパッケージと後のインストールに使える "index.json" ファイ
ルを含むディレクトリを作成します。 このディレクトリ全体をオフラインの
マシンに移し、同梱したランタイムを 1 つ以上インストールできます:

   $> py install --source="<PATH>\index.json" <TAG>...

Python インストールマネージャは、インストーラをダウンロードして別のマ
シンに移してからインストールできます。

あるいは、オフラインインデックスのディレクトリ内にある ZIP ファイルを
別のマシンに転送して展開するだけでも構いません。 この方法ではインスト
ールは一切登録されないため、展開したディレクトリ内の実行ファイルを直接
指定して起動する必要がありますが、Python インストールマネージャをイン
ストールできない場合や不便な場合には、こちらの方が適していることもあり
ます。

このようにして、インターネットにアクセスできないマシンでも Python ラン
タイムをインストールし、管理できます。


4.1.7. ランタイムのアンインストール
-----------------------------------

   $> py uninstall [-y|--yes] <TAG>...

"py uninstall" コマンドを使うと、ランタイムを削除できます。 1 つ以上の
タグを指定しなければなりません。 ここでは範囲指定をサポートしていませ
ん。

"--yes" オプションは、アンインストール前の確認プロンプトを省略します。

タグを個別に渡す代わりに、"--purge" オプションを指定できます。 これは
、スタートメニュー、レジストリ、ダウンロードキャッシュのクリーンアップ
を含め、Python インストールマネージャで管理しているすべてのランタイム
を削除します。 Python インストールマネージャでインストールされていない
ランタイムや、手動で作成した設定ファイルには影響しません。

   $> py uninstall [-y|--yes] --purge

Python インストールマネージャは、Windows の "Installed apps" 設定ペー
ジからアンインストールできます。 グローバルな "python" と "py" コマン
ドは削除されますが、ランタイムは一切削除されず、引き続き使えます。
Python インストールマネージャを再インストールすると、これらのランタイ
ムを再び管理できるようになります。 すべての Python ランタイムを完全に
削除するには、Python インストールマネージャをアンインストールする前に
"--purge" を付けて実行してください。


4.1.8. 設定
-----------

Python インストールマネージャは、設定ファイル、環境変数、コマンドライ
ンオプション、レジストリ設定の階層によって設定します。 一般に、設定フ
ァイルでは、ほかの設定ファイルの場所を含めてすべてを設定できます。 レ
ジストリ設定は管理者だけが使用でき、設定ファイルを上書きします。 コマ
ンドラインオプションはほかのすべての設定を上書きしますが、すべての設定
項目に対応するオプションがあるわけではありません。

この節ではデフォルトの設定を説明しますが、インストールが変更されたり設
定が上書きされたりしている場合は、設定の決定方法が異なることがあります
。

グローバルな設定ファイルは 管理者 が指定でき、最初に読み込まれます。
ユーザ設定ファイルは "%AppData%\Python\pymanager.json" に格納され (こ
の場所は "Local" ではなく "Roaming" の下です)、次に読み込まれて、それ
以前のファイルの設定を上書きします。 追加の設定ファイルは、環境変数
"PYTHON_MANAGER_CONFIG" またはコマンドラインオプション "--config" のい
ずれかで指定できます (両方は使えません)。 これらの場所は、後述する管理
者向けのカスタマイズオプションで変更できます。

以下の設定は、通常の使用で変更する可能性が高いと考えられるものです。
管理者によるカスタマイズを目的とした設定は、後の節に記載します。

-[ 標準の設定オプション ]-

+-----------------------------------+-----------------------------------+-----------------------------------+
| 設定キー                          | 環境変数                          | 説明                              |
|===================================|===================================|===================================|
| "default_tag"                     | PYTHON_MANAGER_DEFAULT            | 起動またはインストールする際の、  |
|                                   |                                   | 優先するデフォルトのバージョンで  |
|                                   |                                   | す。 デフォルトでは、CPython チー |
|                                   |                                   | ムが提供するプレリリース版以外の  |
|                                   |                                   | 最新バージ ョンと解釈します。     |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "default_platform"                | "PYTHON_MANAGER_DEFAULT_PLATFORM" | 起動またはインストールする際の、  |
|                                   |                                   | 優先するデフォルトのプラットフォ  |
|                                   |                                   | ームで す。 指定したタグの接尾辞  |
|                                   |                                   | として扱います。 たとえば、"py    |
|                                   |                                   | -V:3.15" は "3.15-64" のインスト  |
|                                   |                                   | ールが存在すればそれを優先します  |
|                                   |                                   | ("default_platform" が "-64" の場 |
|                                   |                                   | 合) が、そのタグのインストールが  |
|                                   |                                   | なけ れば "3.15" を使います。     |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "logs_dir"                        | "PYTHON_MANAGER_LOGS"             | ログファイルを書き込む場所です。  |
|                                   |                                   | デフォルトは "%TEMP%" です。      |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "automatic_install"               | PYTHON_MANAGER_AUTOMATIC_INSTALL  | true にすると、"py exec" で起動す |
|                                   |                                   | る場合 (または、ランタイムがまだ  |
|                                   |                                   | イン ストールされていないときに   |
|                                   |                                   | "py" で起動する場合) に自動インス |
|                                   |                                   | トールを許 可します。 ほかのコマ  |
|                                   |                                   | ンドは、この設定に関係なく自動イ  |
|                                   |                                   | ンストールを行い ません。 デフォ  |
|                                   |                                   | ルトは true です。                |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "include_unmanaged"               | "PYTHON_MANAGER_INCLUDE_UNMANAGE  | true にすると、Python インストー  |
|                                   | D"                                | ルマネージャでインストールされて  |
|                                   |                                   | いない ランタイムの一覧表示や起動 |
|                                   |                                   | を許可し、false にするとそれらを  |
|                                   |                                   | 除外します。 デフォルトは true で |
|                                   |                                   | す。                              |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "shebang_can_run_anything"        | "PYTHON_MANAGER_SHEBANG_CAN_RUN_  | true にすると、".py" ファイルのシ |
|                                   | ANYTHING"                         | ェバンによる Python ランタイム以  |
|                                   |                                   | 外の アプリケーションの起動を許可 |
|                                   |                                   | し、false にすると禁止します。 デ |
|                                   |                                   | フォルト は true です。           |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "shebang_templates"               | (なし)                            | シェバン行のテンプレートから、"py |
|                                   |                                   | -V:<tag>" などの代替コマンドや置  |
|                                   |                                   | 換文 字列へのマッピングです。 詳  |
|                                   |                                   | しくは シェバン行 を参照してくだ  |
|                                   |                                   | さい。                            |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "log_level"                       | "PYMANAGER_VERBOSE",              | 出力のデフォルトレベル (0–50) を  |
|                                   | "PYMANAGER_DEBUG"                 | 設定します。 デフォルトは 20 です |
|                                   |                                   | 。 値 が小さいほど出力が多くなり  |
|                                   |                                   | ます。 環境変数は真偽値で、起動中 |
|                                   |                                   | に追加の出 力を生成することがあり |
|                                   |                                   | 、この出力は後にほかの設定で抑制  |
|                                   |                                   | されます。                        |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "confirm"                         | "PYTHON_MANAGER_CONFIRM"          | true にすると、アンインストールな |
|                                   |                                   | どの特定の操作を実行する前に確認  |
|                                   |                                   | し、 false にすると確認を省略しま |
|                                   |                                   | す。 デフォルトは true です。     |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "install.source"                  | "PYTHON_MANAGER_SOURCE_URL"       | 新たにインストールするランタイム  |
|                                   |                                   | の取得元となるインデックスフィー  |
|                                   |                                   | ドを上 書きします。               |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "install.enable_entrypoints"      | (なし)                            | true にすると、インストール済みパ |
|                                   |                                   | ッケージ用のグローバルなコマンド  |
|                                   |                                   | ("pip.exe" など) を生成します。   |
|                                   |                                   | これらのコマンドはパッケージ自身  |
|                                   |                                   | が定義 します。 false にすると、  |
|                                   |                                   | Python インタープリタのグローバル |
|                                   |                                   | なコマンドだ けを作成します。 デ  |
|                                   |                                   | フォルトは true です。 この設定を |
|                                   |                                   | 変更した後は、"py install         |
|                                   |                                   | --refresh" を実行してください。   |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "list.format"                     | "PYTHON_MANAGER_LIST_FORMAT"      | "py list" コマンドで使うデフォル  |
|                                   |                                   | トの形式を指定します。 デフォルト |
|                                   |                                   | は "table" です。                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "install_dir"                     | (なし)                            | ランタイムのインストール先となる  |
|                                   |                                   | ルートディレクトリを指定します。  |
|                                   |                                   | この 設定を変更すると、以前にイン |
|                                   |                                   | ストールしたランタイムは、新しい  |
|                                   |                                   | 場所に移動 しない限り使えなくなり |
|                                   |                                   | ます。                            |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "global_dir"                      | (なし)                            | グローバルなコマンド              |
|                                   |                                   | ("python3.15.exe" や "pip.exe" な |
|                                   |                                   | ど) を格納するデ ィレクトリを指定 |
|                                   |                                   | します。 ターミナルからコマンドを |
|                                   |                                   | 使えるようにするには 、このディレ |
|                                   |                                   | クトリを "PATH" に追加してくださ  |
|                                   |                                   | い。                              |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "download_dir"                    | (なし)                            | ダウンロードしたファイルを格納す  |
|                                   |                                   | るディレクトリを指定します。 この |
|                                   |                                   | ディ レクトリは一時的なキャッシュ |
|                                   |                                   | で、ときどきクリーンアップできま  |
|                                   |                                   | す。                              |
+-----------------------------------+-----------------------------------+-----------------------------------+

ドット区切りの名前は JSON オブジェクト内で入れ子にしてください。 たと
えば "list.format" は "{"list": {"format": "table"}}" と指定します。


4.1.9. シェバン行
-----------------

スクリプトファイルの先頭行が "#!" で始まる場合、その行を "シェバン
(shebang)" 行と呼びます。 Linux やほかの Unix 系オペレーティングシステ
ムは、このような行を標準でサポートしており、スクリプトの実行方法を示す
ためによく使われます。 "python" と "py" コマンドを使うと、Windows 上の
Python スクリプトでも同じ機能を使えます。

Python スクリプトのシェバン行を Unix と Windows の間で移植できるように
、使用するインタープリタを指定するためのいくつかの「仮想」コマンドをサ
ポートしています。 サポートする仮想コマンドは次のとおりです:

* "/usr/bin/env <ALIAS>"

* "/usr/bin/env -S <ALIAS>"

* "/usr/bin/<ALIAS>"

* "/usr/local/bin/<ALIAS>"

* "<ALIAS>"

具体的に、もしスクリプトの1行目が

   #! /usr/bin/python

で始まっていたら、デフォルトの Python またはアクティブな仮想環境の位置
が特定され、使用されます。多くの Unix 上で動作する Python スクリプトに
はすでにこの行が存在する傾向がありますので、ランチャによりそれらのスク
リプトを修正なしで使うことができるはずです。あなたが新しいスクリプトを
Windows 上で書いていて、Unix 上でも有用であってほしいと思うなら、シェ
バン行のうち "/usr" で始まるものを使用すべきです。

上記のどの仮想コマンドでも、"<ALIAS>" をインストール済みランタイムのエ
イリアスに置き換えられます。 つまり、グローバルなエイリアス用ディレク
トリ ("PATH" 環境変数に追加しているかもしれません) に生成されるコマン
ドは、"PATH" 上になくてもすべてシェバンで使えます。 これにより、
"/usr/bin/python3.12" のようなシェバンを使って特定のランタイムを選択で
きます。

ランタイムがまったくインストールされていない場合や、自動インストールが
有効な場合は、必要に応じて要求されたランタイムをインストールします。
設定の詳細については、設定 を参照してください。

"/usr/bin/env" 形式のシェバン行では、認識されないコマンドについて
"PATH" 環境変数も検索します。 これは同じ検索を行う Unix の "env" プロ
グラムの動作に対応していますが、既知の Python コマンドの起動を優先しま
す。 任意の実行ファイルを検索する際には警告が表示されることがあり、こ
の検索は "shebang_can_run_anything" 設定オプションで無効にできます。

どのパターンにも一致しないシェバン行は、絶対パス、またはスクリプトファ
イルがあるディレクトリからの相対パスで表した *Windows* 実行ファイルの
パスとして扱います。 この動作は Unix 形式のシェルとは互換性がないため
、インストーラが生成するスクリプトなど、Windows 専用のスクリプトのため
の便宜的な機能です。 これらのパスは引用符で囲むことができ、複数の引数
を含めることもできます。 その後ろにスクリプトのパスと追加の引数を付け
加えます。 この機能は "shebang_can_run_anything" 設定オプションで無効
にできます。

Python インストールマネージャのバージョン 26.3 以降では、カスタムのシ
ェバンテンプレートを設定ファイルに追加できます。 "shebang_templates"
オブジェクトを追加し、各テンプレート (照合する文字列) と、一致した場合
に使うコマンドをメンバーとして指定してください。 ほとんどの場合、イン
ストール済みランタイムのいずれかを起動する "py -V:<tag>" (または
"pyw") をコマンドにします。 "py -3.<version>" 形式や、デフォルトを起動
するための単なる "py" も使えます。 ほかの引数はサポートしていません。

   {
       "shebang_templates": {
           "/usr/bin/python": "py",
           "/usr/bin/my_custom_python": "py -V:MyCustomPython/3"
       }
   }

置換後のコマンドが "py" や "pyw" でなければ、シェバンに書き戻して通常
の処理を続けます。 任意の実行ファイルの起動が許可されている場合は、フ
ルパスを指定することで、Python の代わりに任意の実行ファイルを起動でき
ます。 テンプレートは、行全体 (先頭と末尾の空白は無視します)、またはシ
ェバン行の最初のスペースまでに一致する必要があります。

注釈:

  Python インストールマネージャのシェバンの動作は、従来の "py.exe" ラ
  ンチャとは微妙に異なり、以前の設定オプションは適用されません。 以前
  の動作や設定に明確に依存している場合は、legacy launcher のインストー
  ルをお勧めします。 旧ランチャの "py" コマンドは、デフォルトで
  PyManager のものを上書きするため、インストールやアンインストールには
  "pymanager" コマンドを使う必要があります。


4.1.10. 高度なインストール
--------------------------

古い管理者向け配布プラットフォームなど、MSIX をインストールできない場
合のために、python.org のダウンロードページでは MSI を提供しています。
この MSI にはユーザインターフェースがなく、Program Files 内のデフォル
トの場所へのマシン単位のインストールだけを行えます。 システムの "PATH"
環境変数にこのインストール先を含めるよう変更を試みますが、使用する構成
で必ず検証してください。

注釈:

  CPython がサポートしている Windows のうち、MSIX をサポートしていない
  のは Windows Server 2019 だけです。 Windows Server 2019 では MSI を
  使ってください。

MSI パッケージにはランタイムが同梱されていないため、オフラインインスト
ール用のインデックスも作成しなければ、オフライン環境へのインストールに
は適しません。 このような場合への対処については、オフラインでのインス
トール と 管理者向けの設定 を参照してください。

MSI によってインストールしたランタイムは MSIX によってインストールした
ものと共有され、すべてユーザ単位に限られます。 Python インストールマネ
ージャは、マシン単位のランタイムのインストールをサポートしていません。
マシン単位のインストールを模倣するには、管理者として "py install
--target=<shared location>" を実行し、"PATH"、レジストリ、スタートメニ
ューにシステム全体への変更を自分で追加できます。

MSIX がインストールされていても "PATH" 環境変数からコマンドを使えない
場合は、python.org と Windows Store のどちらからインストールしたかに応
じて、"%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.
PythonManager_3847v3x7pw1km" または "%LocalAppData%\Microsoft\Windows
Apps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0" にあります
。 Program Files から実行ファイルを直接実行しようとすることは推奨しま
せん。

Python インストールマネージャをプログラムからインストールする最も簡単
な方法は、サポート対象のすべての Windows バージョンに含まれている
WinGet を使うことです:

   $> winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity

   # 必要なら設定チェッカーを実行し、すべての変更を受け入れる
   $> py install --configure -y

Python インストールマネージャをダウンロードして別のマシンにインストー
ルするには、次の WinGet コマンドで、必要なファイルを Store からダウン
ロードディレクトリにダウンロードします (出力先を変更するには "-d
<location>" を追加してください)。 このコマンドは YAML ファイルも生成し
ますが、ダウンロードした MSIX は起動するか、以下のコマンドを使ってイン
ストールできるため、このファイルは不要のようです。

   $> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --accept-source-agreements

PowerShell だけを使ってプログラムから MSIX をインストールまたはアンイ
ンストールするには、PowerShell コマンドレットの Add-AppxPackage と
Remove-AppxPackage を推奨します:

   $> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
   ...
   $> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage

AppInstaller ファイルを Add-AppxPackage コマンドに渡すと、Windows が最
新リリースをダウンロードしてインストールできます。 これは python.org
上の MSIX を使ってインストールする方法で、Store からのインストール (対
話的な操作や WinGet によるもの) ができない場合に限って推奨します。

   $> Add-AppxPackage -AppInstallerFile https://www.python.org/ftp/python/pymanager/pymanager.appinstaller

ほかのツールや API を使って、マシン上のすべてのユーザ向けに MSIX パッ
ケージをプロビジョニングすることもできますが、Python はこの利用方法を
サポート対象としていません。 PowerShell の Add-AppxProvisionedPackage
コマンドレット、Windows ネイティブの PackageManager クラス、または使用
している展開ツールのドキュメントやサポートを調べることをお勧めします。

インストール方法に関係なく、ユーザはそれぞれ Python 自体を自分でインス
トールする必要があります。 ログイン済みのユーザ以外が、そのインストー
ルを開始する方法はないためです。 MSIX を使う場合、すべてのユーザがネッ
トワークにアクセスせずに最新バージョンの Python をインストールできます
。

Note that the MSIX downloadable from the Store and from the Python
website are subtly different and cannot be installed at the same time.
Wherever possible, we suggest using the above WinGet commands to
download the package from the Store to reduce the risk of setting up
conflicting installs. There are no licensing restrictions on the
Python install manager that would prevent using the Store package in
this way.


4.1.11. 管理者向けの設定
------------------------

Python インストールマネージャの設定を管理者が上書きする際に役立つオプ
ションがいくつかあります。 これらを使うと、ローカルキャッシュの提供、
特定の種類のショートカットの無効化、同梱コンテンツの上書きができます。
上記の設定オプションはすべて設定でき、以下の設定も使えます。

レジストリの "HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager"
の下に、設定キーと一致する値名、"REG_SZ" 型の値を設定すると、設定オプ
ションを上書きできます。 このキー自体もカスタマイズできますが、Python
インストールマネージャに付属するコア設定ファイルを変更する方法に限られ
ます。 ただし、レジストリの値は、上書きする設定一式を含む JSON ファイ
ルを "base_config" に指定するためだけに使うことをお勧めします。 レジス
トリキーによる上書きは、ほかの方法で指定した設定をすべて置き換えますが
、"base_config" を使えば、ユーザが必要な設定をさらに変更できます。

環境変数を使える設定のほとんどは、デフォルト値にその変数を指定すること
で対応している点に注意してください。 これらの設定を上書きすると、別の
環境変数で上書きしない限り、環境変数は使われなくなります。 たとえば、
"confirm" のデフォルト値は文字どおり "%PYTHON_MANAGER_CONFIRM%" で、読
み込み時にこの変数を解決します。 値を "yes" に上書きすると、その環境変
数は使われなくなります。 値を "%CONFIRM%" に上書きすると、代わりにそち
らの環境変数を使います。

パスを指定する設定は、そのパスを指定した設定ファイルがあるディレクトリ
からの相対パスとして解釈します。

-[ 管理者向けの設定オプション ]-

+----------------------------------------------------+----------------------------------------------------+
| 設定キー                                           | 説明                                               |
|====================================================|====================================================|
| "base_config"                                      | 最優先で読み込む設定ファイルです。 この設定は、組  |
|                                                    | み込みの設定ファイル とレジストリだけが変更できま  |
|                                                    | す。                                               |
+----------------------------------------------------+----------------------------------------------------+
| "user_config"                                      | 2 番目に読み込む設定ファイルです。                 |
+----------------------------------------------------+----------------------------------------------------+
| "additional_config"                                | 3 番目に読み込む設定ファイルです。                 |
+----------------------------------------------------+----------------------------------------------------+
| "registry_override_key"                            | 設定の上書きを確認するレジストリ内の場所です。 こ  |
|                                                    | の設定は、組み込みの 設定ファイルだけが変更できま  |
|                                                    | す。                                               |
+----------------------------------------------------+----------------------------------------------------+
| "bundled_dir"                                      | ローカルにキャッシュしたファイルを含む、読み出し専 |
|                                                    | 用のディレクトリです 。                            |
+----------------------------------------------------+----------------------------------------------------+
| "install.fallback_source"                          | メインのインデックスにアクセスできない場合に参照す |
|                                                    | る、インデックスのパ スまたは URL です。           |
+----------------------------------------------------+----------------------------------------------------+
| "install.enable_shortcut_kinds"                    | 許可するショートカットの種類のカンマ区切りリスト ( |
|                                                    | たとえば ""pep514,start"") です。 有効にしたショー |
|                                                    | トカットも、 "disable_shortcut_kinds" で無効にでき |
|                                                    | ます。                                             |
+----------------------------------------------------+----------------------------------------------------+
| "install.disable_shortcut_kinds"                   | 除外するショートカットの種類のカンマ区切りリスト ( |
|                                                    | たとえば ""pep514,start"") です。 無効にしたショー |
|                                                    | トカットが "enable_shortcut_kinds" によって再び有  |
|                                                    | 効になることはありません。                         |
+----------------------------------------------------+----------------------------------------------------+
| "install.hard_link_entrypoints"                    | true にすると、ディスク領域を節約するために、グロ  |
|                                                    | ーバルなショートカッ トにハードリンクを使います。  |
|                                                    | false にすると、代わりに各ショートカット の実行フ  |
|                                                    | ァイルをコピーします。 この設定を変更した後は、既  |
|                                                    | 存のコマンド を更新するために "py install          |
|                                                    | --refresh --force" を実行しなければなりま せん。   |
|                                                    | デフォルトは true です。 トラブルシューティングや  |
|                                                    | 、ファイルのリ ンクに問題があるシステムでは、この  |
|                                                    | 設定を無効にする必要があるかもしれま せん。        |
+----------------------------------------------------+----------------------------------------------------+
| "pep514_root"                                      | PEP 514 のエントリを読み書きする、レジストリ内の場 |
|                                                    | 所です。 デフォルト は                             |
|                                                    | "HKEY_CURRENT_USER\Software\Python" です。         |
+----------------------------------------------------+----------------------------------------------------+
| "start_folder"                                     | ショートカットを書き込むスタートメニューのフォルダ |
|                                                    | です。 デフォルトは "Python" です。 このパスは、ユ |
|                                                    | ーザの Programs フォルダからの相対パスで す。      |
+----------------------------------------------------+----------------------------------------------------+
| "virtual_env"                                      | アクティブな仮想環境へのパスです。 デフォルトは    |
|                                                    | "%VIRTUAL_ENV%" ですが 、空にすると venv の検出を  |
|                                                    | 無効にできます。                                   |
+----------------------------------------------------+----------------------------------------------------+
| "shebang_can_run_anything_silently"                | true にすると、シェバンが Python ランタイム以外の  |
|                                                    | アプリケーションを起 動するときに表示する警告を抑  |
|                                                    | 制します。                                         |
+----------------------------------------------------+----------------------------------------------------+
| "source_settings"                                  | 取得元の URL から、そのインデックスに固有の設定へ  |
|                                                    | のマッピングです。 複 数の設定ファイルがこの節を含 |
|                                                    | む場合、URL ごとの設定は追加または上書きし ますが  |
|                                                    | 、個々の設定をマージすることはありません。 これら  |
|                                                    | の設定は、現在 のところ インデックスの署名 専用で  |
|                                                    | す。                                               |
+----------------------------------------------------+----------------------------------------------------+


4.1.12. フリースレッドバイナリのインストール
--------------------------------------------

Added in version 3.13.

"t" 接尾辞の付いたタグをインストールすると、フリースレッドビルドのビル
ド済みディストリビューションを入手できます。

   $> py install 3.15t
   $> py install 3.15t-arm64
   $> py install 3.15t-32

通常どおりインストールして登録します。 ほかのランタイムがインストール
されていなければ、"python" はこのランタイムを起動します。 そうでなけれ
ば "py -V:3.15t" を使うか、グローバルなエイリアス用ディレクトリを
"PATH" 環境変数に追加している場合は "python3.15t.exe" コマンドを使う必
要があります。


4.1.13. インデックスの署名
--------------------------

Added in version 26.2.

インデックスファイルには、改ざんを検出するための署名を付けられます。
署名は、インデックスと同じ URL で、ファイル名に ".cat" を付けたカタロ
グファイルです。 カタログファイルには、対応するインデックスファイルの
ハッシュを含め、有効な Authenticode 署名で署名する必要があります。 こ
のため、(Windows 上の) 標準的なツールで署名を生成でき、クライアントの
オペレーティングシステムがその認証局 (ルート CA) を既に信頼している限
り、どの証明書でも使えます。

インデックスの署名をダウンロードして検証するのは、ローカル設定の
"source_settings" 節にインデックスの URL が含まれ、
"requires_signature" が true の場合、またはインデックスの JSON で
"requires_signature" が true に設定されている場合だけです。 ローカル設
定にこの設定があれば、値が false の場合でも、インデックス内の設定は無
視します。

有効な署名を要求することに加え、"required_root_subject" と
"required_publisher_subject" の設定で、証明書の Subject フィールドに基
づいて受け入れ可能な署名をさらに制限できます。 設定で指定した属性はす
べて、証明書の属性と一致しなければなりません (証明書に含まれる、それ以
外の属性は無視します)。 典型的な属性には、共通名の "CN="、組織の "O="
、発行元の国の "C=" があります。

最後に、"required_publisher_eku" 設定では、発行元の証明書に特定の拡張
キー使用法 (Enhanced Key Usage、EKU) が割り当てられていることを要求で
きます。 たとえば EKU "1.3.6.1.5.5.7.3.3" は、証明書が (サーバやクライ
アントの認証ではなく) コード署名を目的としていることを示します。 特定
のルート CA と組み合わせることで、正当な署名であることを検証するもう 1
つの仕組みになります。

以下は、設定ファイルの "source_settings" 節の例です。 この場合、
Microsoft Identity Verification のルートと、そのルートが割り当てた EKU
の組み合わせによって、フィードの発行元を一意に識別します。 この場合の
署名は "https://www.python.org/ftp/python/index-windows.json.cat" にあ
ります。

   {
     "source_settings": {
       "https://www.python.org/ftp/python/index-windows.json": {
         "requires_signature": true,
         "required_root_subject": "CN=Microsoft Identity Verification Root Certificate Authority 2020",
         "required_publisher_subject": "CN=Python Software Foundation",
         "required_publisher_eku": "1.3.6.1.4.1.311.97.608394634.79987812.305991749.578777327"
       }
     }
   }

代わりに "index.json" ファイル内で同じ設定を指定することもできます。
この場合はルートと EKU を省略しており、署名が有効で、発行元の証明書に
特定の共通名がある必要がありますが、ほかの検証は行いません。

   {
     "requires_signature": true,
     "required_publisher_subject": "CN=Python Software Foundation",
     "versions": [
       // ...
     ]
   }

フィード内の設定を使う場合は、ユーザに通知し、設定をログファイルや詳細
出力に表示します。 頻繁に使うフィードでは、これらの設定をローカルの設
定ファイルにコピーすることを推奨します。 これにより、フィードが不正に
変更されても検証を無効にできなくなります。

署名ファイルの場所を、フィード内や設定ファイルで上書きすることはできま
せん。 管理者は、強制適用する設定ファイルで独自の "source_settings" を
指定できます (管理者向けの設定 を参照)。

署名の検証に失敗すると、通知が表示され、続行するか確認を求められます。
対話的な確認が許可されていない場合 (たとえば "--yes" が指定された場合)
は、常に中断します。 この状況で無効な設定を持つフィードを使うには、そ
のフィードの署名検証を無効にする設定ファイルを用意しなければなりません
。

   "source_settings": {
     "https://www.example.com/feed-with-invalid-signature.json": {
       "requires_signature": false
     }
   }


4.1.14. プロキシの設定
----------------------

Added in version 26.4.

デフォルトでは、Python インストールマネージャは自動認証を含め、システ
ム全体のプロキシ設定を使います。 ほとんどのユーザにとって、この動作は
ブラウザやほかのアプリケーションと同じです。

設定を上書きするには、環境変数 "NO_PROXY"、"HTTP_PROXY"、"HTTPS_PROXY"
を使ってください。 これらは、Python インストールマネージャを使う前にタ
ーミナルセッション内で設定してください。 ほかのアプリケーションもこれ
らの変数を使う可能性があるため、マシン全体のグローバルな設定にする際は
注意してください。

"NO_PROXY" に空でない値を設定すると、あらゆるプロキシの使用を無効にし
ます。 システムのデフォルトのプロキシ設定を迂回し、インデックスサーバ
に直接アクセスを試みる場合に使ってください。

"HTTPS_PROXY" に "example.com:8080" のような文字列を設定すると、すべて
の HTTPS 接続でそのプロキシサーバに接続します。 デフォルトのインデック
スではすべての接続が HTTPS を使うため、通常はこの設定を上書きします。

暗号化した接続を使わないプライベートなインデックスサーバを使い、デフォ
ルトのプロキシサーバを上書きする必要がある場合は、"HTTP_PROXY" 変数が
必要になるかもしれません。 形式は "HTTPS_PROXY" と同じです。

認証情報はどちらの設定にも埋め込めますが、"HTTPS_PROXY" に認証情報が埋
め込まれていれば、ほかの認証情報よりも優先して使います。 両方の種類の
プロキシで、1 組の認証情報だけを使います。


4.1.15. トラブルシューティング
------------------------------

Python インストールマネージャが正しく動作していないようであれば、以下
の確認と修正を順に試してください。 解決しなければ、関連するログファイ
ル (デフォルトでは "%TEMP%" ディレクトリに書き込まれます) を添えて、バ
グトラッカー に問題を報告してください。

-[ トラブルシューティング ]-

+----------------------------------------------------+----------------------------------------------------+
| 症状                                               | 試すこと                                           |
|====================================================|====================================================|
| ターミナルに "python" と入力すると、"command not   | Python インストールマネージャをインストールしまし  |
| found" エラーが出るか 、Store アプリが開く。       | たか?                                              |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | スタートをクリックして "Manage app execution       |
|                                                    | aliases" を開き、"Python (default)" のエイリアスが |
|                                                    | 有効であることを確認してください。 既に有効で あれ |
|                                                    | ば、無効にしてから再度有効にし、コマンドを更新して |
|                                                    | みてください。 "Python (default windowed)" と      |
|                                                    | "Python install manager" のコマンドも更 新が必要か |
|                                                    | もしれません。                                     |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | "py" と "pymanager" コマンドが動作することを確認し |
|                                                    | てください。                                       |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | "PATH" 変数に "%UserProfile%\AppData\Local\Micros  |
|                                                    | oft\WindowsApps" のエ ントリが含まれていることを確 |
|                                                    | 認してください。 オペレーティングシステム は、デフ |
|                                                    | ォルトでほかのユーザパスの後にこのエントリを 1 つ  |
|                                                    | 含めています 。 削除すると、ショートカットが見つか |
|                                                    | らなくなります。                                   |
+----------------------------------------------------+----------------------------------------------------+
| ターミナルに "py" と入力すると、"command not       | Python インストールマネージャをインストールしまし  |
| found" エラーが出る。                              | たか?                                              |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | スタートをクリックして "Manage app execution       |
|                                                    | aliases" を開き、"Python (default)" のエイリアスが |
|                                                    | 有効であることを確認してください。 既に有効で あれ |
|                                                    | ば、無効にしてから再度有効にし、コマンドを更新して |
|                                                    | みてください。 "Python (default windowed)" と      |
|                                                    | "Python install manager" のコマンドも更 新が必要か |
|                                                    | もしれません。                                     |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | "PATH" 変数に "%UserProfile%\AppData\Local\Micros  |
|                                                    | oft\WindowsApps" のエ ントリが含まれていることを確 |
|                                                    | 認してください。 オペレーティングシステム は、デフ |
|                                                    | ォルトでほかのユーザパスの後にこのエントリを 1 つ  |
|                                                    | 含めています 。 削除すると、ショートカットが見つか |
|                                                    | らなくなります。                                   |
+----------------------------------------------------+----------------------------------------------------+
| ターミナルに "py" コマンドを入力すると、"can't     | 通常これは、旧ランチャがインストールされていて、   |
| open file" エラーが出る 。                         | Python インストールマ ネージャよりも優先されている |
|                                                    | ことを意味します。 削除するには、スタート をクリッ |
|                                                    | クして "Installed apps" を開き、"Python launcher"  |
|                                                    | を検索してア ンインストールしてください。          |
+----------------------------------------------------+----------------------------------------------------+
| "python" と "py" が異なるランタイムを起動する      | スタートをクリックして "Installed apps" を開き、既 |
|                                                    | 存の Python ランタイ ムを探して、削除するか、      |
|                                                    | Modify を選んで "PATH" のオプションを無効にし てく |
|                                                    | ださい。                                           |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | スタートをクリックして "Manage app execution       |
|                                                    | aliases" を開き、 "python.exe" エイリアスが        |
|                                                    | "Python (default)" に設定されていることを確 認して |
|                                                    | ください                                           |
+----------------------------------------------------+----------------------------------------------------+
| "python" と "py" が期待したランタイムを起動しない  | 環境変数 "PYTHON_MANAGER_DEFAULT" または           |
|                                                    | "default_tag" 設定を確認して ください。 "py list"  |
|                                                    | コマンドは、これらの設定に基づいたデフォルトを表   |
|                                                    | 示します。                                         |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | Python インストールマネージャで管理しているインス  |
|                                                    | トールは、管理してい ないインストールよりも優先し  |
|                                                    | て選択されます。 "py install" で目的のラン タイム  |
|                                                    | をインストールするか、デフォルトのタグを設定してく |
|                                                    | ださい。                                           |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | Python インストールマネージャで管理していないプレ  |
|                                                    | リリース版や実験的な インストールは、安定版よりも  |
|                                                    | 優先して選択されることがあります。 デフォ ルトのタ |
|                                                    | グを設定するか、プレリリース版のランタイムをアンイ |
|                                                    | ンストールし て、"py install" で再インストールして |
|                                                    | ください。                                         |
+----------------------------------------------------+----------------------------------------------------+
| "pythonw" や "pyw" が、"python" や "py" と異なるラ | スタートをクリックして "Manage app execution       |
| ンタイムを起動する                                 | aliases" を開き、 "pythonw.exe" と "pyw.exe" のエ  |
|                                                    | イリアスがほかのエイリアスと整合してい ることを確  |
|                                                    | 認してください。                                   |
+----------------------------------------------------+----------------------------------------------------+
| ターミナルに "pip" と入力すると、"command not      | 仮想環境をアクティブにしていますか? ターミナルで   |
| found" エラーが出る。                              | ".venv\Scripts\activate" スクリプトを実行してアク  |
|                                                    | ティブにしてください 。                            |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | パッケージは使える状態でも、生成される実行ファイル |
|                                                    | がない可能性がありま す。 代わりに "python -m pip" |
|                                                    | コマンドを使うことを推奨します。 "py install       |
|                                                    | --refresh" を実行し、グローバルなショートカット用  |
|                                                    | ディレクトリ が "PATH" 上にあることを確認すると (  |
|                                                    | なければコマンドの出力に表示されま す)、"pip" (や  |
|                                                    | ほかのインストール済みパッケージ) などのコマンドが |
|                                                    | 使える ようになるはずです。                        |
+----------------------------------------------------+----------------------------------------------------+
| "pip" でパッケージをインストールしたが、そのコマン | 仮想環境をアクティブにしていますか? ターミナルで   |
| ドが見つからない。                                 | ".venv\Scripts\activate" スクリプトを実行してアク  |
|                                                    | ティブにしてください 。                            |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | 新しいパッケージをインストールしても、Python イン  |
|                                                    | ストールマネージャは グローバルなショートカットを  |
|                                                    | 自動的には作成しません。 同様に、パッケー ジをアン |
|                                                    | インストールしても、そのショートカットは削除しませ |
|                                                    | ん。 "py install --refresh" を実行して、新たにイン |
|                                                    | ストールしたパッケージのグロ ーバルなショートカッ  |
|                                                    | トを更新してください。                             |
+----------------------------------------------------+----------------------------------------------------+
| ターミナルに "script-name.py" と入力すると、新しい | これは、オペレーティングシステムの既知の制限です。 |
| ウィンドウが開く。                                 | スクリプト名の前に "py" を指定するか、スクリプトと |
|                                                    | 同じ名前で "@py "%~dpn0.py" %*" を含む バッチファ  |
|                                                    | イルを作成するか、legacy launcher をインストールし |
|                                                    | てスクリプ トの関連付けとして選択してください。    |
+----------------------------------------------------+----------------------------------------------------+
| スクリプトへのファイルのドラッグアンドドロップが動 | これは、オペレーティングシステムの既知の制限です。 |
| 作しない                                           | legacy launcher を 使う場合、または MSI からインス |
|                                                    | トールした Python インストールマネージ ャを使う場  |
|                                                    | 合にはサポートしています。                         |
+----------------------------------------------------+----------------------------------------------------+
| Python インストールマネージャを複数回インストール  | It is possible to install from the Store or        |
| してしまった。                                     | WinGet, from the MSIX on the Python website, and   |
|                                                    | from the MSI, all at once. They are all compatible |
|                                                    | and will share configuration and runtimes.         |
+----------------------------------------------------+----------------------------------------------------+
|                                                    | 通常の Installed Apps (プログラムの追加と削除) 設  |
|                                                    | 定ページを使わずにイ ンストールマネージャをアンイ  |
|                                                    | ンストールする方法については、前述の 高度 なインス |
|                                                    | トール の節を参照してください。                    |
+----------------------------------------------------+----------------------------------------------------+
| 以前の "py.ini" 設定が使えなくなった。             | 新しい Python インストールマネージャは、この設定フ |
|                                                    | ァイルとその設定をサ ポートしなくなったため、これ  |
|                                                    | らを無視します。 設定の詳細については、設 定 を参  |
|                                                    | 照してください。                                   |
+----------------------------------------------------+----------------------------------------------------+


4.2. 埋め込み可能なパッケージ
=============================

Added in version 3.5.

埋め込み用の配布 (embedded distribution) は、最小限の Python 環境を含
んだ ZIP ファイルです。これは、エンドユーザから直接的にアクセスされる
のではなく何かアプリケーションの一部として動作することを意図したもので
す。

埋め込み用の配布をインストールするには、"py install" に "--target" オ
プションを付けて使うことをお勧めします:

   $> py install 3.15-embed --target=<directory>

展開した埋め込み用の配布は、環境変数、システムのレジストリ設定、インス
トール済みパッケージを含め、ユーザのシステムから (ほぼ) 完全に分離され
ています。 標準ライブラリは、事前にコンパイル・最適化した ".pyc" ファ
イルとして ZIP 内に含まれており、"python3.dll"、"python315.dll"、
"python.exe"、"pythonw.exe" はすべて提供されます。 Tcl/Tk (IDLE など、
Tcl/Tk に依存するものすべてを含みます)、pip、Python ドキュメントは含ま
れていません。

デフォルトの "._pth" ファイルが含まれており、デフォルトの検索パスをさ
らに制限します (後述の モジュールの検索 で説明します)。 このファイルは
、埋め込む側が必要に応じて変更することを意図しています。

サードパーティのパッケージはアプリケーションのインストーラによって、埋
め込み用配布と同じ場所にインストールされるべきです。通常の Python イン
ストレーションのように依存性管理に pip を使うことは、この配布ではサポ
ートされません。ですが、ちょっとした注意を払えば、自動更新のために pip
を含めて利用することはできるかもしれません。一般的には、ユーザに更新を
提供する前に開発者が新しいバージョンとの互換性を保証できるよう、サード
パーティーのパッケージはアプリケーションの一部として扱われるべきです
("vendoring")。

この配布の 2 つのお勧めできるユースケースを、以下で説明します。


4.2.1. Python アプリケーション
------------------------------

Python で書かれたアプリケーションでも、必ずしもユーザにその事実を意識
させる必要はありません。 この場合は、埋め込み用の配布を使って、インス
トールパッケージに専用の Python を含めることができます。 ユーザに
Python の存在をどの程度意識させずに使ってもらいたいか (あるいは逆に、
どの程度本格的なアプリケーションに見せたいか) に応じて、2 つの選択肢が
あります。

専用の実行ファイルをランチャとして使うには多少のコーディングが必要です
が、ユーザが Python の存在を最も意識せずに使える方法です。 カスタマイ
ズしたランチャでは、プログラムが Python 上で動いていることを示す明白な
目印はありません。 アイコンをカスタマイズでき、会社名やバージョン情報
を指定でき、ファイルの関連付けも適切に動作します。 ほとんどの場合、カ
スタムランチャは、ハードコードしたコマンドラインで "Py_Main" を呼び出
すだけで済むはずです。

より簡単なアプローチは、 "python.exe" または "pythonw.exe" を必要なコ
マンドライン引数とともに直接呼び出すバッチファイルかショートカットを提
供することです。この場合、そのアプリケーションは実際の名前ではなく
Python であるようにみえるので、ほかに動作している Python プロセスやフ
ァイルの関連付けと区別するのにユーザが困るかもしれません。

後者のアプローチではパッケージは、パス上で利用可能であることを保証する
ために、Python 実行ファイルと同じディレクトリにインストールされるべき
です。特別なランチャの場合はアプリケーション起動前に検索パスを指定する
機会があるので、パッケージはほかの場所に配置できます。


4.2.2. Python の埋め込み
------------------------

ネイティブコードで書かれたアプリケーションでは、何らかのスクリプト言語
が必要になることがよくあり、Python の埋め込み用の配布をこの目的に使え
ます。 一般に、アプリケーションの大半はネイティブコードで書かれ、一部
が "python.exe" を呼び出すか、"python3.dll" を直接使います。 どちらの
場合も、埋め込み用の配布をアプリケーションのインストール先のサブディレ
クトリに展開すれば、読み込み可能な Python インタープリタを提供できます
。

アプリケーションでの利用と同様に、インタープリタの初期化前に検索パスを
指定できるため、パッケージは任意の場所にインストールできます。 それ以
外は、埋め込み用の配布と通常のインストールとの間に根本的な違いはありま
せん。


4.3. nuget.org パッケージ
=========================

Added in version 3.5.2.

nuget.org パッケージはサイズを縮小した Python 環境で、システム全体で使
える Python が無い継続的インテグレーションやビルドシステムで使うことを
意図しています。 nuget は ".NET のためのパッケージマネージャ" ですが、
ビルド時に使うツールを含んだパッケージに対しても非常に上手く動作します
。

nuget の使用方法についての最新の情報を得るには nuget.org に行ってくだ
さい。 ここから先は Python 開発者にとって十分な要約です。

コマンドラインツール "nuget.exe" は、たとえば curl や PowerShell を使
って "https://dist.nuget.org/win-x86-commandline/latest/nuget.exe" か
ら直接ダウンロードできます。 このツールでは、次のようにして 64 ビット
または 32 ビットのマシン向けの最新バージョンの Python をインストールし
ます。

   nuget.exe install python -ExcludeVersion -OutputDirectory .
   nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .

特定のバージョンを選択するには、"-Version 3.x.y" を追加してください。
出力ディレクトリは "." から変更でき、パッケージはそのサブディレクトリ
にインストールされます。 デフォルトではサブディレクトリはパッケージと
同じ名前になり、"-ExcludeVersion" オプションを付けないと、インストール
したバージョンも名前に含まれます。 そのサブディレクトリの中に、Python
のインストールを含む "tools" ディレクトリがあります:

   # -ExcludeVersion を付けない場合
   > .\python.3.5.2\tools\python.exe -V
   Python 3.5.2

   # -ExcludeVersion を付けた場合
   > .\python\tools\python.exe -V
   Python 3.5.2

一般に、nuget パッケージはアップグレードできないため、新しいバージョン
は既存のものと並べてインストールし、フルパスで参照してください。 ある
いは、パッケージのディレクトリを手動で削除して、再度インストールしてく
ださい。 多くの CI システムでは、ビルド間でファイルを保持しない場合、
この作業を自動的に行います。

"tools" ディレクトリと同じ階層に "build\native" ディレクトリがあります
。 ここには MSBuild のプロパティファイル "python.props" があり、C++ プ
ロジェクトで Python のインストールを参照するために使えます。 この設定
を取り込むと、ビルドでヘッダとインポートライブラリを自動的に使うように
なります。

nuget.org 上のパッケージ情報のページは、64 ビット版が
www.nuget.org/packages/python、32 ビット版が
www.nuget.org/packages/pythonx86、ARM64 版が
www.nuget.org/packages/pythonarm64 です。


4.3.1. フリースレッドパッケージ (Free-threaded packages)
--------------------------------------------------------

Added in version 3.13.

フリースレッドバイナリを含むパッケージの名前は、64 ビット版が python-
freethreaded、32 ビット版が pythonx86-freethreaded、ARM64 版が
pythonarm64-freethreaded です。 これらのパッケージには
"python3.15t.exe" と "python.exe" の両方のエントリポイントが含まれてお
り、どちらもフリースレッドで実行します。


4.4. 別のバンドル
=================

標準の CPython の配布物の他に、追加の機能を持っている修正されたパッケ
ージがあります。以下は人気のあるバージョンとそのキーとなる機能です:

ActivePython
   マルチプラットフォーム互換のインストーラー、ドキュメント、 PyWin32

Anaconda
   人気のある (numpy, scipy や pandas のような) 科学系モジュールと、パ
   ッケージマネージャ "conda" 。

Enthought Deployment Manager
   "次世代の Python 環境とパッケージマネージャー" ("The Next
   Generation Python Environment and Package Manager")。

   以前は Enthought が Canopy を提供していましたが、これは 2016 年にサ
   ポートが終了しました。

WinPython
   ビルド済みの科学系パッケージと、パッケージのビルドのためのツールを
   含む、Windows 固有のディストリビューション。

これらパッケージは Python や他のライブラリの最新バージョンが含まれると
は限りませんし、コア Python チームはこれらを保守もしませんしサポートも
しませんのでご理解ください。


4.5. サポートする Windows のバージョン
======================================

**PEP 11** に定められているとおり、Python の各リリースは、Microsoft が
Windows プラットフォームを延長サポートの対象としている間だけ、そのプラ
ットフォームをサポートします。 つまり、Python 3.15 は Windows 10 以降
をサポートします。 Windows 7 のサポートが必要な場合は Python 3.8 をイ
ンストールしてください。 Windows 8.1 のサポートが必要な場合は Python
3.12 をインストールしてください。


4.6. MAX_PATH の制限の解除
==========================

Windows は歴史的にパスの長さが 260 文字に制限されています。 つまり、こ
れより長いパスは解決できず結果としてエラーになるということです。

最新バージョンの Windows では、この制限を 32,000 文字を超える長さに拡
張できます。 管理者が "Enable Win32 long paths" グループポリシーを有効
にするか、レジストリキー
"HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem" の
"LongPathsEnabled" を "1" に設定する必要があります。

これにより、 "open()" 関数や "os" モジュール、他のほとんどのパスの機能
が 260 文字より長いパスを受け入れ、返すことができるようになります。

上記のオプションを変更して再起動すると、それ以上の設定は必要ありません
。


4.7. UTF-8 モード
=================

Added in version 3.7.

バージョン 3.15 で変更: Python UTF-8 モードは、デフォルトで有効になり
ました (**PEP 686**)。

Windows は、システムのエンコーディング (ANSI コードページ) として、今
でも従来のエンコーディングを使っています。 Python UTF-8 モード が無効
な場合、Python は "locale.getencoding()" が返す ANSI コードページを、
テキストファイルのデフォルトのエンコーディングとして使います。

インターネットや、WSL (Windows Subsystem for Linux) を含むほとんどの
Unix システムでは UTF-8 が広く使われているため、これが問題を引き起こす
ことがあります。

デフォルトで有効な Python UTF-8 モード は、システムのエンコーディング
を無視し、デフォルトのテキストエンコーディングとして UTF-8 を使います
。 UTF-8 モード が有効な場合でも、"mbcs" コーデックを通じてシステムの
エンコーディング (ANSI コードページ) を使えます。

コマンドラインオプション "-X utf8=0" または環境変数 "PYTHONUTF8=0" に
よって、Python UTF-8 モード を無効にできます。 UTF-8 モードの無効化に
ついては "PYTHONUTF8" を、環境変数の変更方法については Python インスト
ールマネージャ を参照してください。

ヒント:

  デフォルトの環境変数に "PYTHONUTF8={0,1}" を追加すると、システム上の
  すべての Python 3.7 以降のアプリケーションに影響します。 従来のシス
  テムエンコーディングに依存する Python 3.7 以降のアプリケーションがあ
  る場合は、環境変数を一時的に設定するか、コマンドラインオプション "-X
  utf8" を使うことを推奨します。

注釈:

  UTF-8 モードが無効でも、Windows 上では Python は次の用途にデフォルト
  で UTF-8 を使います:

  * 標準入出力を含むコンソール入出力 (詳細は **PEP 528** を参照)。

  * *ファイルシステムのエンコーディング* (詳細は **PEP 529** を参照)。


4.8. モジュールの検索
=====================

以下では、sys.path モジュール検索パスの初期化 の説明を補足する、
Windows 固有の詳細を説明します。

"._pth" ファイルが見付からなかったときは、 Windows では "sys.path" は
次のように設定されます:

* 最初に空のエントリが追加されます。これはカレントディレクトリを指して
  います。

* 環境変数 で説明する環境変数 "PYTHONPATH" が存在する場合は、次にその
  エントリを追加します。 Windows では、ドライブ識別子 ("C:\" など) に
  使うコロンと区別するため、この変数内のパスはセミコロンで区切る必要が
  あります。

* 追加の「アプリケーションパス」は、レジストリの "HKEY_CURRENT_USER"
  と "HKEY_LOCAL_MACHINE" の両ハイブの下にある
  "\SOFTWARE\Python\PythonCore{version}\PythonPath" のサブキーとして追
  加できます。 デフォルト値がセミコロン区切りのパス文字列であるサブキ
  ーがあると、各パスを "sys.path" に追加します。 (既知のインストーラは
  すべて HKLM だけを使うため、HKCU は通常空です。)

* 環境変数 "PYTHONHOME" が設定されている場合は、それを「Python Home」
  とみなします。 そうでなければ、Python のメインの実行ファイルのパスを
  使って「目印となるファイル」("Lib\os.py" または "pythonXY.zip") を探
  し、「Python Home」を推定します。 Python Home が見つかれば、そのフォ
  ルダに基づいたサブディレクトリ ("Lib" や "plat-win" など) を
  "sys.path" に追加します。 そうでなければ、レジストリに格納されている
  PythonPath から Python のコアパスを構築します。

* Python Home が見つからず、環境に "PYTHONPATH" が指定されておらず、レ
  ジストリエントリも見つからない場合は、相対的なエントリを含むデフォル
  トのパス (たとえば ".\Lib;.\plat-win") を使います。

メインの実行ファイルと同じ場所か一つ上のディレクトリに "pyvenv.cfg" が
ある場合、以下の異なった規則が適用されます:

* "PYTHONHOME" が設定されておらず、 "home" が絶対パスの場合、home 推定
  の際メインの実行ファイルから推定するのではなくこのパスを使います。

結果としてこうなります:

* "python.exe" または Python のメインディレクトリにあるほかの .exe を
  実行する場合 (インストール済みのバージョンでも、PCbuild ディレクトリ
  から直接実行する場合でも)、コアパスを推定し、レジストリ内のコアパス
  は無視します。 レジストリ内のほかの「アプリケーションパス」は常に読
  み込みます。

* Python をほかの .exe 内で動作させる場合 (たとえば、別のディレクトリ
  内で動作させる場合や、COM 経由で埋め込む場合)、「Python Home」は推定
  されないため、レジストリ内のコアパスを使います。 レジストリ内のほか
  の「アプリケーションパス」は常に読み込みます。

* Python がホームを見つけられず、レジストリの値もない場合 (凍結した
  .exe や、非常に特殊なインストール構成の場合)、いくつかのデフォルトの
  相対パスを含むパスになります。

自身のアプリケーションや配布物に Python をバンドルしたい場合には、以下
の助言 (のいずれかまたは組合せ) によりほかのインストレーションとの衝突
を避けることができます:

* 実行ファイルと同じ場所に、含めたいディレクトリを列挙した "._pth" フ
  ァイルを置いてください。 これにより、レジストリや環境変数に記載され
  たパスを無視し、"import site" を列挙していない限り "site" も無視しま
  す。

* 自身の実行ファイル内で "python3.dll" または "python315.dll" を読み込
  む場合は、"Py_InitializeFromConfig()" の前に
  "PyConfig.module_search_paths" を明示的に設定してください。

* 自身のアプリケーションから "python.exe" を起動する前に、
  "PYTHONPATH" をクリアしたり上書きし、 "PYTHONHOME" をセットしてくだ
  さい。

* 上記の方法を使えない場合 (たとえば、"python.exe" の直接実行を利用者
  に許可するディストリビューションの場合)、インストールディレクトリ内
  に目印となるファイル ("Lib\os.py") があることを確認してください。
  (ZIP ファイル内にあるものは検出されませんが、代わりに、正しい名前の
  ZIP ファイルが検出されます。)

これらはシステムワイドにインストールされたファイルが、あなたのアプリケ
ーションにバンドルされた標準ライブラリのコピーに優先しないようにします
。これをしなければあなたのアプリケーションのユーザは、何かしら問題を抱
えるかもしれません。上で列挙した最初の提案が最善です。ほかのものはレジ
ストリ内の非標準のパスやユーザの site-packages の影響を少し受けやすい
からです。

バージョン 3.6 で変更: "._pth" ファイルのサポートを追加し、
"pyvenv.cfg" の "applocal" オプションを削除しました。

バージョン 3.6 で変更: 実行ファイルと同じディレクトリにある
"python*XX*.zip" を、目印となるファイルの候補として追加しました。

バージョン 3.6 で非推奨: レジストリの "Modules" ("PythonPath" ではあり
ません) に指定されたモジュールは、
"importlib.machinery.WindowsRegistryFinder" がインポートすることがあり
ます。 このファインダーは、Windows 上の 3.6.0 以前では有効ですが、将来
は "sys.meta_path" への明示的な追加が必要になるかもしれません。


4.9. 追加のモジュール
=====================

Python は全プラットフォーム互換を目指していますが、 Windows にしかない
ユニークな機能もあります。標準ライブラリと外部のライブラリの両方で、幾
つかのモジュールと、そういった機能を使うためのスニペットがあります。

Windows 固有の標準モジュールは、 MS Windows 固有のサービス に書かれて
います。


4.9.1. PyWin32
--------------

Mark Hammond による PyWin32 モジュールは、Windows 固有の高度なサポート
を提供するモジュール群です。 次のものに対応するユーティリティを含んで
います:

* Component Object Model (COM)

* Win32 API 呼び出し

* レジストリ

* イベントログ

* Microsoft Foundation Classes (MFC) のユーザインターフェース

PythonWin は PyWin32 に付属している、サンプルのMFCアプリケーションです
。これはビルトインのデバッガを含む、組み込み可能なIDEです。

参考:

  Win32 How Do I...?
     by Tim Golden

  Python and COM
     by David and Paul Boddie


4.9.2. cx_Freeze
----------------

cx_Freeze は、Python スクリプトを Windows の実行可能なプログラム
("***.exe" ファイル) にまとめます。 これを使うと、ユーザに Python のイ
ンストールを求めずにアプリケーションを配布できます。


4.10. Windows 上で Python をコンパイルする
==========================================

CPython を自分でコンパイルしたい場合、最初にすべきことは ソース を取得
することです。最新リリース版のソースか、新しい チェックアウト をダウン
ロードできます。

ソースツリーには Microsoft Visual Studio でのビルドのソリューションフ
ァイルとプロジェクトファイルが含まれていて、これが公式の Python リリー
スに使われているコンパイラです。これらファイルは "PCbuild" ディレクト
リ内にあります。

ビルドプロセスについての一般的な情報は、"PCbuild/readme.txt" にありま
す。

拡張モジュールについては、 Windows 上での C および C++ 拡張モジュール
のビルド を参照してください。


4.11. 完全版インストーラ (非推奨)
=================================

バージョン 3.14 で非推奨: このインストーラは 3.14 から非推奨で、Python
3.16 以降では作成されません。 現在のインストーラについては Python イン
ストールマネージャ を参照してください。


4.11.1. インストール手順
------------------------

ダウンロードできる Python 3.15 のインストーラは 4 つあります。 インタ
プリタの 32 ビット版、64 ビット版がそれぞれ 2 つずつあります。 *WEB イ
ンストーラ* は最初のダウンロードサイズは小さく、必要なコンポーネントは
インストーラ実行時に必要に応じて自動的にダウンロードします。 *オフライ
ンインストーラ* にはデフォルトインストールに必要なコンポーネントが含ま
れていて、インターネット接続はオプショナルな機能のためにだけに必要とな
ります。 インストール時にダウンロードを避けるほかの方法については ダウ
ンロードせずにインストールする を参照して下さい。

インストーラを開始すると、2つの選択肢からひとつを選べます:

[画像]

"Install Now" を選択した場合:

* 管理者権限は *不要です* (ただし C ランタイムライブラリのシステム更新
  が必要であったり、 Python インストールマネージャ をすべてのユーザ向
  けにインストールする場合は必要です)。

* Python はあなたのユーザディレクトリにインストールされます。

* Python インストールマネージャ はこのインストールウィザード最初のペー
  ジの下部のチェックボックス指定に従ってインストールされます。

* 標準ライブラリ、テストスイート、ランチャ、pip がインストールされます
  。

* このインストールウィザード最初の下部のチェックボックスをチェックすれ
  ば、環境変数 "PATH" にインストールディレクトリが追加されます。

* ショートカットはカレントユーザだけに可視になります。

"Customize installation" を選択すると、インストールする機能やインスト
ール先、ほかのオプション、インストール後の操作を選べます。 デバッグシ
ンボルやデバッグバイナリをインストールするには、このオプションを使う必
要があります。

すべてのユーザのためのインストールのためには "Customize installation"
を選んでください。この場合:

* 管理者資格か承認が必要かもしれません。

* Python は Program Files ディレクトリにインストールされます。

* Python インストールマネージャ は Windows ディレクトリにインストール
  されます。

* オプショナルな機能はインストール中に選択できます。

* 標準ライブラリをバイトコードにプリコンパイルできます。

* そう選択すれば、インストールディレクトリはシステム環境変数 "PATH" に
  追加されます。

* ショートカットがすべてのユーザで利用できるようになります。


4.11.2. MAX_PATH の制限の解除
-----------------------------

Windows は歴史的にパスの長さが 260 文字に制限されています。 つまり、こ
れより長いパスは解決できず結果としてエラーになるということです。

Windows の最新版では、この制限は約 32,000 文字まで拡張できます。 管理
者が、グループポリシーの "Win32 の長いパスを有効にする (Enable Win32
long paths)" を有効にするか、レジストリキー
"HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem" の
"LongPathsEnabled" の値を "1" に設定する必要があります。

これにより、 "open()" 関数や "os" モジュール、他のほとんどのパスの機能
が 260 文字より長いパスを受け入れ、返すことができるようになります。

これらのオプションを変更したら、それ以上の設定は必要ありません。

バージョン 3.6 で変更: Python で長いパスのサポートが可能になりました。


4.11.3. UI を使わないインストール
---------------------------------

インストーラの GUI で利用できるすべてのオプションは、コマンドラインか
らも指定できます。これによりユーザとの対話なしで数多くの機器に同じイン
ストールを行うような、スクリプト化されたインストールを行うことができま
す。ちょっとしたデフォルトの変更のために、GUI を抑制することなしにこれ
らコマンドラインオプションをセットすることもできます。

インストーラーには、以下のオプション ("/?" でインストーラを実行するこ
とで確認できます) を渡すことができます:

+-----------------------+----------------------------------------------------------+
| 名前                  | 説明                                                     |
|=======================|==========================================================|
| /passive              | ユーザーの操作なしでも進捗を表示する                     |
+-----------------------+----------------------------------------------------------+
| /quiet                | UI を表示せずにインストール・アンインストールする        |
+-----------------------+----------------------------------------------------------+
| /simple               | ユーザーによるカスタマイズができないようにする           |
+-----------------------+----------------------------------------------------------+
| /uninstall            | (確認無しで) Python を削除する                           |
+-----------------------+----------------------------------------------------------+
| /layout [ディレクトリ | すべてのコンポーネントを事前にダウンロードする           |
| ]                     |                                                          |
+-----------------------+----------------------------------------------------------+
| /log [ファイル名]     | ログファイルの場所を指定する                             |
+-----------------------+----------------------------------------------------------+

ほかのすべてのオプションは "name=value" の形で渡します。value は大抵
"0" で機能を無効化、 "1" で機能を有効化、であるとかパスの指定です。利
用可能なオプションの完全なリストは以下の通りです。

+-----------------------------+----------------------------------------+----------------------------+
| 名前                        | 説明                                   | デフォルト                 |
|=============================|========================================|============================|
| InstallAllUsers             | システムワイドなインストールを実行する | 0                          |
|                             | 。                                     |                            |
+-----------------------------+----------------------------------------+----------------------------+
| TargetDir                   | インストール先ディレクトリ。           | InstallAllUsers に基いて選 |
|                             |                                        | 択されます。               |
+-----------------------------+----------------------------------------+----------------------------+
| DefaultAllUsersTargetDir    | すべてのユーザ向けインストールのための | "%ProgramFiles%\Python     |
|                             | デフォルトインストール先ディレク トリ  | X.Y" または "%ProgramFile  |
|                             | 。                                     | s(x86)%\Python X.Y"        |
+-----------------------------+----------------------------------------+----------------------------+
| DefaultJustForMeTargetDir   | 自分一人用インストールのためのデフォル | "%LocalAppData%\Programs\  |
|                             | トインストール先ディレクトリ。         | Python\PythonXY" または "  |
|                             |                                        | %LocalAppData%\Programs\P  |
|                             |                                        | ython\PythonXY-32" または  |
|                             |                                        | "%LocalAppData%\Programs\  |
|                             |                                        | Python\PythonXY-64"        |
+-----------------------------+----------------------------------------+----------------------------+
| DefaultCustomTargetDir      | カスタムインストールディレクトリとして | (空)                       |
|                             | デフォルトで GUI に表示される値 。     |                            |
+-----------------------------+----------------------------------------+----------------------------+
| AssociateFiles              | ランチャもインストールする場合に、ファ | 1                          |
|                             | イルの関連付けを行う。                 |                            |
+-----------------------------+----------------------------------------+----------------------------+
| CompileAll                  | すべての ".py" ファイルをバイトコンパ  | 0                          |
|                             | イルして ".pyc" を作る。               |                            |
+-----------------------------+----------------------------------------+----------------------------+
| PrependPath                 | "PATH" にインストールディレクトリと    | 0                          |
|                             | Scripts ディレクトリを先頭に追加し 、  |                            |
|                             | "PATHEXT" に ".PY" を追加する。        |                            |
+-----------------------------+----------------------------------------+----------------------------+
| AppendPath                  | "PATH" の末尾にインストールディレクト  | 0                          |
|                             | リと Scripts ディレクトリを追加し 、   |                            |
|                             | "PATHEXT" に ".PY" を追加する。        |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Shortcuts                   | インストールするインタプリタ、ドキュメ | 1                          |
|                             | ント、IDLE へのショートカットを 作る。 |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_doc                 | Python マニュアルをインストールする。  | 1                          |
+-----------------------------+----------------------------------------+----------------------------+
| Include_debug               | デバッグバイナリをインストールする。   | 0                          |
+-----------------------------+----------------------------------------+----------------------------+
| Include_dev                 | 開発者用ヘッダーとライブラリをインスト | 1                          |
|                             | ールする。これを省略すると、使用 不可  |                            |
|                             | 能なインストールになる可能性があります |                            |
|                             | 。                                     |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_exe                 | "python.exe" と関連するファイルをイン  | 1                          |
|                             | ストールする。これを省略すると、 使用  |                            |
|                             | 不可能なインストールになる可能性があり |                            |
|                             | ます。                                 |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_launcher            | Python インストールマネージャ をインス | 1                          |
|                             | トールする。                           |                            |
+-----------------------------+----------------------------------------+----------------------------+
| InstallLauncherAllUsers     | すべてのユーザーにランチャーをインスト | 1                          |
|                             | ールする。 "Include_launcher" が 1 に  |                            |
|                             | 設定されている必要があります。         |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_lib                 | 標準ライブラリと拡張モジュールをインス | 1                          |
|                             | トールする。これを省略すると、使 用不  |                            |
|                             | 可能なインストールになる可能性がありま |                            |
|                             | す。                                   |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_pip                 | バンドル版の pip と setuptools をイン  | 1                          |
|                             | ストールする。                         |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_symbols             | デバッグシンボル ("*.pdb") をインスト  | 0                          |
|                             | ールする。                             |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_tcltk               | Tcl/Tk サポートと IDLE をインストール  | 1                          |
|                             | する。                                 |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_test                | 標準ライブラリのテストスイートをインス | 1                          |
|                             | トールする。                           |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_tools               | ユーティリティスクリプトをインストール | 1                          |
|                             | する。                                 |                            |
+-----------------------------+----------------------------------------+----------------------------+
| LauncherOnly                | ランチャのみをインストールする。これは | 0                          |
|                             | 他のほとんどのオプションを上書き しま  |                            |
|                             | す。                                   |                            |
+-----------------------------+----------------------------------------+----------------------------+
| SimpleInstall               | インストール UI の大部分を無効にする。 | 0                          |
+-----------------------------+----------------------------------------+----------------------------+
| SimpleInstallDescription    | 単純化されたインストーラ GUI を使う際  | (空)                       |
|                             | に表示するカスタムメッセージ。         |                            |
+-----------------------------+----------------------------------------+----------------------------+

たとえば、デフォルトのシステム全体向けの Python をユーザの操作なしでイ
ンストールするには、管理者権限のコマンドプロンプトから次のコマンドを使
えます。

   python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0

テストスイートなしの Python のパーソナルなコピーのインストールをユーザ
に簡単に行わせるには、以下コマンドのショートカットを作れば良いです。こ
れはインストーラの最初のページを単純化して表示し、また、カスタマイズで
きないようにします:

   python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
       SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."

(ランチャのインストールを省略するとファイルの関連付けも省略されるので
、これはランチャインストールを含めたシステムワイドなインストールをした
場合のユーザごとインストールに限った場合のお勧めです。)

上でリストしたオプションは、実行ファイルと同じ場所の "unattend.xml" と
名付けられたファイルで与えることもできます。このファイルはオプションと
その値のリストを指定します。値がアトリビュートとして与えられた場合、そ
れは数値であれば数値に変換されます。エレメントテキストで与える場合は常
に文字列のままです。以下は、先の例と同じオプションをセットするファイル
の実例です:

   <Options>
       <Option Name="InstallAllUsers" Value="no" />
       <Option Name="Include_launcher" Value="0" />
       <Option Name="Include_test" Value="no" />
       <Option Name="SimpleInstall" Value="yes" />
       <Option Name="SimpleInstallDescription">Just for me, no test suite</Option>
   </Options>


4.11.4. ダウンロードせずにインストールする
------------------------------------------

Python の一部の機能は最初にダウンロードするインストーラに含まれていな
いため、それらを選択するとインターネット接続が必要になることがあります
。 この接続を不要にするには、必要に応じて利用可能なすべてのコンポーネ
ントをダウンロードし、完全な *配置構成 (layout)* を作成できます。 これ
により、選択した機能に関係なく、以後のインターネット接続が不要になりま
す。 このダウンロードは必要以上に大きくなるかもしれませんが、大量のイ
ンストールを行う場合には、ローカルにキャッシュしたコピーがあると非常に
便利です。

必要になる可能性のあるファイルをすべてダウンロードするには、コマンドプ
ロンプトから次のコマンドを実行してください。 "python-3.9.0.exe" は実際
のインストーラの名前に置き換え、同名ファイルの衝突を避けるため、配置構
成はそれぞれ専用のディレクトリに作成してください。

   python-3.9.0.exe /layout [optional target directory]

進捗表示を隠すのに "/quiet" オプションを指定することもできます。


4.11.5. インストール後の変更
----------------------------

いったん Python がインストールされたら、Windows のシステム機能の「プロ
グラムと機能」ツールから機能の追加や削除ができます。Python のエントリ
を選択して「アンインストールと変更」を選ぶことで、インストーラをメンテ
ナンスモードで開きます。

インストーラ GUI で "Modify" を選ぶと、チェックボックスの選択を変える
ことで機能の追加削除ができます - チェックボックスの選択を変えなければ
、何かがインストールされたり削除されたりはしません。いくつかのオプショ
ンはこのモードでは変更することはできません。インストールディレクトリな
どです。それらを変えたいのであれば、完全に削除してから再インストールす
る必要があります。

"Repair" では、現在の設定で本来インストールされるべきすべてのファイル
を検証し、削除されていたり更新されていたりするファイルを修正します。

"Uninstall" は、Python インストールマネージャ を除いて Python を完全に
削除します。 ランチャには、「プログラムと機能」に独立したエントリがあ
ります。


4.11.6. フリースレッドバイナリのインストール
--------------------------------------------

Added in version 3.13.

フリースレッドが有効なビルド済みバイナリ (**PEP 703** を参照) をインス
トールするには、"Customize installation" を選択してください。 オプショ
ンの 2 ページ目に "Download free-threaded binaries" チェックボックスが
あります。

[画像]

このオプションを選択すると、メインの Python のインストールと同じ場所に
追加のバイナリをダウンロードしてインストールします。 メインの実行ファ
イルは "python3.13t.exe" という名前で、ほかのバイナリには "t" 接尾辞ま
たは完全な ABI 接尾辞が付きます。 Python のソースファイルや同梱のサー
ドパーティの依存ライブラリは、メインのインストールと共有します。

フリースレッド版は、タグ "3.13t" を持つ通常の Python インストールとし
て登録されます (32 ビットや ARM64 のプラットフォームでは、通常どおり
"-32" または "-arm64" 接尾辞が付きます)。 これにより、ツールがこのイン
ストールを検出でき、Python インストールマネージャ が "py.exe -3.13t"
をサポートできます。 ランチャは "py.exe -3" (または "python3" のシェバ
ン) を「最新の 3.x のインストール」と解釈するため、通常のバイナリより
もフリースレッドバイナリを優先しますが、"py.exe -3.13" ではそうならな
い点に注意してください。 短い形式のオプションを使う場合は、現時点では
フリースレッドバイナリをインストールしない方がよいかもしれません。

コマンドラインでインストールオプションを指定するには、
"Include_freethreaded=1" を使ってください。 オフラインインストールに備
えて追加のバイナリを事前にダウンロードする手順については、ダウンロード
せずにインストールする を参照してください。 デバッグシンボルやデバッグ
バイナリを含めるオプションは、フリースレッドビルドにも適用されます。

フリースレッドバイナリは nuget.org でも入手できます。


4.12. Windows 用 Python ランチャ (非推奨)
=========================================

バージョン 3.14 で非推奨: このランチャとそのドキュメントは、前述の
Python インストールマネージャに置き換えられました。 歴史的な資料として
、一時的に残しています。

Added in version 3.3.

Windows の Python ランチャは、異なる Python のバージョンの位置の特定と
実行を助けるユーティリティです。スクリプト (またはコマンドライン) で特
定の Python のバージョンの設定を与えられると、位置を特定し、そのバージ
ョンを実行します。

環境変数 "PATH" による方法と違って、このランチャは Python の一番適切な
バージョンを、正しく選択します。このランチャはシステムワイドなものより
もユーザごとのインストレーションの方を優先し、また、新しくインストール
された順よりも言語のバージョンを優先します。

ランチャのオリジナルの仕様は **PEP 397** にあります。


4.12.1. 最初に
--------------


4.12.1.1. コマンドラインから起動する
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

バージョン 3.6 で変更.

Python 3.3 とそれ以降のシステムワイドなインストールでは、ランチャーが
"PATH" に追加されます。ランチャーは、入手可能なあらゆる Python のバー
ジョンに互換性があるため、実際にどのバージョンの Python がインストール
されているのかは重要ではありません。ランチャーが使えるかを確認するには
以下のコマンドをコマンドプロンプトで実行してください:

   py

インストールされている最新バージョンの Python が起動するはずです。 通
常どおりに終了することもできますし、追加のコマンドライン引数を指定して
直接 Python に渡すこともできます。

複数のバージョンの Python (たとえば 3.7 と 3.15) がインストールされて
いる場合は、Python 3.15 が起動することになります。Python 3.7 を起動し
たいなら、次のコマンドを実行してみてください:

   py -3.7

インストールしてある Python 2 の最新バージョンを起動したい場合は、次の
コマンドを実行してみてください:

   py -2

以下のようなエラーが出るようであれば、ランチャはインストールされていま
せん:

   'py' is not recognized as an internal or external command,
   operable program or batch file.

このコマンド:

   py --list

これは、現在インストールされている Python のバージョンを表示します。

"-x.y" 引数は "-V:Company/Tag" 引数の短縮形です。 後者の引数では、
python.org 以外から入手したものも含め、特定の Python ランタイムを選択
できます。 **PEP 514** に従って登録されたランタイムはすべて検出できま
す。 "--list" コマンドは、利用可能なすべてのランタイムを "-V:" 形式で
一覧表示します。

"-V:" 引数を使う場合、Company を指定すると、その提供元のランタイムだけ
が選択対象になり、Tag だけを指定するとすべての提供元から選択します。
スラッシュを省略するとタグとして解釈される点に注意してください。

   # タグが '3.*' の任意のランタイムを選択
   py -V:3

   # 'PythonCore' がリリースした任意のランタイムを選択
   py -V:PythonCore/

   # PythonCore の最新の Python 3 ランタイムを選択
   py -V:PythonCore/3

引数の短縮形 ("-3") は、常にコア Python のリリースだけを選択対象とし、
ほかのディストリビューションからは選択しません。 一方、長い形式
("-V:3") はすべてを選択対象とします。

Company は、大文字・小文字を区別せずに文字列全体を照合します。 Tag は
、文字列全体、またはその次の文字がドットかハイフンである接頭辞と照合し
ます。 これにより "-V:3.1" は "3.1-32" に一致しますが、"3.10" には一致
しません。 タグの並べ替えは数値順 ("3.10" は "3.1" より新しい) で行い
ますが、比較は文字列として行います ("-V:3.01" は "3.1" に一致しません)
。


4.12.1.2. 仮想環境 (Virtual environments)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added in version 3.5.

Python のバージョンを明示的に指定せずにランチャを実行し、仮想環境 (標
準ライブラリの "venv" モジュールや外部ツール "virtualenv" で作成したも
の) がアクティブな場合は、グローバルなインタープリタではなく、その仮想
環境のインタープリタを実行します。 グローバルなインタープリタを実行す
るには、仮想環境を非アクティブにするか、グローバルな Python のバージョ
ンを明示的に指定してください。


4.12.1.3. スクリプトから起動する
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

テスト用の Python スクリプトを作成しましょう。"hello.py" という名前で
以下の内容のファイルを作成してください

   #! python
   import sys
   sys.stdout.write("hello from Python %s\n" % (sys.version,))

hello.py が存在するディレクトリで、下記コマンドを実行してください:

   py hello.py

インストールされている最新の Python 2.x のバージョン番号が表示されるは
ずです。では、1行目を以下のように変更してみてください:

   #! python3

コマンドを再実行すると、今度は最新の Python 3.x の情報が表示されるはず
です。これまでのコマンドラインの例と同様に、より細かいバージョン修飾子
を指定することもできます。Python 3.7 がインストールされている場合、最
初の行を "#! python3.7" に変更すると、3.7 のバージョン情報が表示される
はずです。

コマンドからの呼び出しとは異なり、後ろに何もつかない "python" はインス
トールされている Python2.x の最新バージョンを利用することに注意してく
ださい。これは後方互換性と、 "python" が一般的に Python 2 を指すUnix
との互換性のためです。


4.12.1.4. ファイルの関連付けから起動する
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

インストール時に、ランチャは Python ファイル (すなわち ".py", ".pyw",
".pyc" ファイル) に関連付けられたはずです。そのため、これらのファイル
を Windows のエクスプローラーでダブルクリックした際はランチャが使われ
、上で述べたのと同じ機能を使ってスクリプトが使われるべきバージョンを指
定できるようになります。

このことによる重要な利点は、単一のランチャが先頭行の内容によって複数の
Python バージョンを同時にサポートできることです。


4.12.2. シェバン行
------------------

スクリプトファイルの先頭の行が "#!" で始まっている場合は、その行はシェ
バン (shebang) 行として知られています。 Linux や他の Unix 系 OS はこう
した行をもともとサポートしているため、それらのシステムでは、スクリプト
がどのように実行されるかを示すために広く使われます。 Windows の Python
ランチャは、Windows 上の Python スクリプトが同じ機能を使用できるように
し、上の例ではそれらの機能の使用法を示しています。

Python スクリプトのシェバン行を Unix と Windows の間で移植できるように
、このランチャは、使用するインタープリタを指定するためのいくつかの「仮
想」コマンドをサポートしています。 サポートする仮想コマンドは次のとお
りです:

* "/usr/bin/env"

* "/usr/bin/python"

* "/usr/local/bin/python"

* "python"

具体的に、もしスクリプトの1行目が

   #! /usr/bin/python

で始まっていたら、デフォルトの Python またはアクティブな仮想環境の位置
が特定され、使用されます。多くの Unix 上で動作する Python スクリプトに
はすでにこの行が存在する傾向がありますので、ランチャによりそれらのスク
リプトを修正なしで使うことができるはずです。あなたが新しいスクリプトを
Windows 上で書いていて、Unix 上でも有用であってほしいと思うなら、シェ
バン行のうち "/usr" で始まるものを使用すべきです。

上記のどの仮想コマンドでも、(メジャーバージョンだけや、メジャー・マイ
ナーバージョンの両方で) 明示的にバージョンを指定できます。 さらに、
"-32" をマイナーバージョンの後ろに追加して 32-bit 版を要求できます。
例えば、 "/usr/bin/python3.7-32" は 32-bit の Python 3.7 を使うよう要
求します。仮想環境がアクティブになっている場合は、バージョンは無視され
、その環境が使用されます。

Added in version 3.7: python ランチャの 3.7 からは、末尾に "-64" を付
けて 64-bit 版を要求できます。 さらに、マイナーバージョン無しのメジャ
ーバージョンとアーキテクチャだけ (例えば、 "/usr/bin/python3-64") で指
定できます。

バージョン 3.11 で変更: "-64" 接尾辞は非推奨で、現在は「i386/32 ビット
であると確認できない任意のアーキテクチャ」を意味します。 特定の環境を
要求するには、新しい "-V:*TAG*" 引数に完全なタグを指定してください。

バージョン 3.13 で変更: "python" を参照する仮想コマンドは、"PATH" を検
索するよりも、アクティブな仮想環境を優先するようになりました。 これは
、シェバンで "/usr/bin/env python3" を指定しているのに、アクティブな環
境に "python3.exe" がない場合に対応するためです。

"/usr/bin/env" 形式のシェバン行には、もう 1 つ特別な性質があります。
この形式では、インストール済みの Python インタープリタを探す前に、実行
ファイルの "PATH" を検索し、最初の引数で指定した名前に一致する Python
実行ファイルを探します。 これは、"PATH" の検索を行う Unix の "env" プ
ログラムの動作に対応します。 "env" コマンドの後にある最初の引数に一致
する実行ファイルが見つからず、その引数が "python" で始まる場合は、ほか
の仮想コマンドについて説明した方法で処理します。 環境変数
"PYLAUNCHER_NO_SEARCH_PATH" に任意の値を設定すると、この "PATH" の検索
を省略できます。

これらのどのパターンにも一致しないシェバン行は、ランチャの .INI ファイ
ル の "[commands]" 節で検索します。 これを使うと、特定のコマンドをシス
テムに適した方法で処理できます。 コマンド名は 1 つの引数でなければなら
ず (シェバン内の実行ファイル名にスペースは使えません)、置換する値は実
行ファイルのフルパスです (.INI 内に追加の引数を指定すると、ファイル名
の一部として引用符で囲まれます)。

   [commands]
   /bin/xpython=C:\Program Files\XPython\python.exe

.INI ファイルに見つからないコマンドは、絶対パス、またはスクリプトファ
イルがあるディレクトリからの相対パスで表した **Windows** 実行ファイル
のパスとして扱います。 この動作は Unix 形式のシェルとは互換性がないた
め、インストーラが生成するスクリプトなど、Windows 専用のスクリプトのた
めの便宜的な機能です。 これらのパスは引用符で囲むことができ、複数の引
数を含めることもできます。 その後ろにスクリプトのパスと追加の引数を付
け加えます。


4.12.3. シェバン行の引数
------------------------

シェバン行では Python インタプリタに渡される追加の引数を指定することも
できます。たとえば、シェバン行に以下のように書かれているとしましょう:

   #! /usr/bin/python -v

この場合、Python は "-v" オプション付きで起動するでしょう


4.12.4. カスタマイズ
--------------------


4.12.4.1. INI ファイルによるカスタマイズ
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ランチャは2つの .ini ファイルを探しに行きます。具体的には、現在のユー
ザーのアプリケーションデータディレクトリ ("%LOCALAPPDATA%" または
"$env:LocalAppData") の "py.ini" と、ランチャと同じディレクトリにある
"py.ini" です。'コンソール' 版のランチャ (つまり py.exe) と 'Windows'
版のランチャ (つまり pyw.exe) は同一の .ini ファイルを使用します。

"application data" ディレクトリで指定された設定は、実行ファイルの隣に
あるものより優先されます。そのため、ランチャの隣にある .ini ファイルへ
の書き込みアクセスができないユーザは、グローバルな .ini ファイル内のコ
マンドを上書き (override) できます。


4.12.4.2. デフォルトのPythonバージョンのカスタマイズ
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

どのバージョンの Python をコマンドで使用するかを定めるため、バージョン
修飾子がコマンドに含められることがあります。 バージョン修飾子はメジャ
ーバージョン番号で始まり、オプションのピリオド ('.') とマイナーバージ
ョン指定子がそれに続きます。 さらに、 "-32" や "-64" を追記して 32-bit
あるいは 64-bit のどちらの実装が要求されるかを指示できます。

たとえば、"#!python" というシェバン行はバージョン修飾子を含みませんが
、"#!python3" はメジャーバージョンを指定するバージョン修飾子を含みます
。

コマンドにバージョン修飾子がない場合は、環境変数 "PY_PYTHON" でデフォ
ルトのバージョン修飾子を指定できます。 設定されていなければ、デフォル
トは "3" です。 この変数には、"3"、"3.7"、"3.7-32"、"3.7-64" など、コ
マンドラインで渡せる任意の値を指定できます。 ("-64" オプションを使える
のは、Python 3.7 以降に含まれるランチャだけです。)

マイナーバージョン修飾子が見つからない場合、環境変数
"PY_PYTHON{major}" (ここで "{major}" は、上記で決定された現在のメジャ
ーバージョン修飾子) を設定して完全なバージョンを指定することができます
。そういったオプションが見つからなければ、ランチャはインストール済みの
Python バージョンを列挙して、見つかったそのメジャーバージョン向けマイ
ナーリリースのうち最新のものを使用します。保証されているわけではありま
せんが、通常はそのメジャーバージョン系で最も後にインストールしたバージ
ョンになります。

64-bit Windows で、同一の (major.minor) Python バージョンの 32-bit と
64-bit の両方の実装がインストールされていた場合、64-bit バージョンのほ
うが常に優先されます。これはランチャが 32-bit と 64-bit のどちらでも言
えることで、32-bit のランチャは、指定されたバージョンが使用可能であれ
ば、64-bit の Python を優先して実行します。これは、どのバージョンが PC
にインストールされているかのみでランチャの挙動を予見でき、それらがイン
ストールされた順番に関係なくなる (つまり最後にインストールされた
Python とランチャが 32-bit か 64-bit かを知らなくともよい) ようにする
ためです。上に記したとおり、オプションの "-32", "-64" サフィックスでこ
の挙動を変更できます。

例:

* 関連するオプションが設定されていない場合、"python" および "python2"
  コマンドはインストールされている最新の Python 2.x バージョンを使用し
  、"python3" コマンドはインストールされている最新の Python 3.x を使用
  します。

* "python3.7" コマンドは、バージョンが完全に指定されているため、全くオ
  プションを参照しません。

* "PY_PYTHON=3" の場合、"python" および "python3" コマンドはともにイン
  ストールされている最新の Python 3 を使用します。

* "PY_PYTHON=3.7-32" の場合、"python" コマンドは 32-bit 版の 3.7 を使
  用しますが、"python3" コマンドはインストールされている最新の Python
  を使用します (メジャーバージョンが指定されているため、PY_PYTHON は全
  く考慮されません。)

* "PY_PYTHON=3" で "PY_PYTHON3=3.7" の場合、"python" および "python3"
  はどちらも 3.7 を使用します

環境変数に加え、同じ設定をランチャが使う INI ファイルで構成することが
できます。INI ファイルの該当するセクションは "[defaults]" と呼ばれ、キ
ー名は環境変数のキー名から "PY_" という接頭辞を取ったものと同じです
(INI ファイルのキー名は大文字小文字を区別しないことにご注意ください)。
環境変数の内容は INI ファイルでの指定を上書きします。

例えば:

* "PY_PYTHON=3.7" と設定することは、INI ファイルに下記が含まれることと
  等価です:

   [defaults]
   python=3.7

* "PY_PYTHON=3" と "PY_PYTHON3=3.7" を設定することは、INI ファイルに下
  記が含まれることと等価です:

   [defaults]
   python=3
   python3=3.7


4.12.5. 診断
------------

環境変数 "PYLAUNCHER_DEBUG" に任意の値を設定すると、ランチャは標準エラ
ー出力 (つまりコンソール) に診断情報を表示します。 この情報には冗長で
ありながら簡潔すぎる面もありますが、検出された Python のバージョン、特
定のバージョンを選択した理由、対象の Python の実行に使った正確なコマン
ドラインを確認できるはずです。 主にテストとデバッグを目的としています
。


4.12.6. ドライラン
------------------

環境変数 "PYLAUNCHER_DRYRUN" に任意の値を設定すると、ランチャは実行す
るはずのコマンドを出力しますが、実際には Python を起動しません。 これ
は、ランチャで Python を検出してから直接起動したいツールに役立つことが
あります。 標準出力に書き込むコマンドは常に UTF-8 でエンコードされるた
め、コンソールでは正しく表示されない可能性がある点に注意してください。


4.12.7. 必要に応じたインストール
--------------------------------

環境変数 "PYLAUNCHER_ALLOW_INSTALL" に任意の値が設定されていて、要求さ
れた Python のバージョンがインストールされておらず、Microsoft Store で
入手可能な場合、ランチャはそのインストールを試みます。 完了するにはユ
ーザの操作が必要になることがあり、コマンドを再実行する必要があるかもし
れません。

追加の変数 "PYLAUNCHER_ALWAYS_INSTALL" を使うと、Python が検出された場
合でも、ランチャは常に Python のインストールを試みます。 これは主にテ
ストを目的としています ("PYLAUNCHER_DRYRUN" と組み合わせて使ってくださ
い)。


4.12.8. 戻りコード
------------------

Python ランチャは、次の終了コードを返すことがあります。 残念ながら、こ
れらを Python 自体の終了コードと区別する方法はありません。

コードの名前はソース内で使われているもので、参考として記載しています。
このページを読む以外に、これらの名前にアクセスしたり、対応する値を取得
したりする方法はありません。 エントリは名前のアルファベット順に記載し
ています。

+---------------------+---------+-------------------------------------------------+
| 名前                | 値      | 説明                                            |
|=====================|=========|=================================================|
| RC_BAD_VENV_CFG     | 107     | "pyvenv.cfg" が見つかりましたが、壊れています。 |
+---------------------+---------+-------------------------------------------------+
| RC_CREATE_PROCESS   | 101     | Python の起動に失敗しました。                   |
+---------------------+---------+-------------------------------------------------+
| RC_INSTALLING       | 111     | インストールが開始されましたが、完了後にコマン  |
|                     |         | ドを再実行する必要があり ます。                 |
+---------------------+---------+-------------------------------------------------+
| RC_INTERNAL_ERROR   | 109     | 予期しないエラーです。 バグを報告してください。 |
+---------------------+---------+-------------------------------------------------+
| RC_NO_COMMANDLINE   | 108     | オペレーティングシステムからコマンドラインを取  |
|                     |         | 得できません。                                  |
+---------------------+---------+-------------------------------------------------+
| RC_NO_PYTHON        | 103     | 要求されたバージョンが見つかりません。          |
+---------------------+---------+-------------------------------------------------+
| RC_NO_VENV_CFG      | 106     | "pyvenv.cfg" が必要ですが、見つかりませんでした |
|                     |         | 。                                              |
+---------------------+---------+-------------------------------------------------+
