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_UNMANAGED	true にすると、Python インストールマネージャでインストールされていないランタイムの一覧表示や起動を許可し、false にするとそれらを除外します。 デフォルトは true です。
shebang_can_run_anything	PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING	true にすると、.py ファイルのシェバンによる Python ランタイム以外のアプリケーションの起動を許可し、false にすると禁止します。 デフォルトは true です。
shebang_templates	(なし)	シェバン行のテンプレートから、py -V:<tag> などの代替コマンドや置換文字列へのマッピングです。 詳しくは シェバン行 を参照してください。
log_level	PYMANAGER_VERBOSE, PYMANAGER_DEBUG	出力のデフォルトレベル (0–50) を設定します。 デフォルトは 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\WindowsApps\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 found" エラーが出るか、Store アプリが開く。	Python インストールマネージャをインストールしましたか?
	スタートをクリックして "Manage app execution aliases" を開き、"Python (default)" のエイリアスが有効であることを確認してください。 既に有効であれば、無効にしてから再度有効にし、コマンドを更新してみてください。 "Python (default windowed)" と "Python install manager" のコマンドも更新が必要かもしれません。
	py と pymanager コマンドが動作することを確認してください。
	PATH 変数に %UserProfile%\AppData\Local\Microsoft\WindowsApps のエントリが含まれていることを確認してください。 オペレーティングシステムは、デフォルトでほかのユーザパスの後にこのエントリを 1 つ含めています。 削除すると、ショートカットが見つからなくなります。
ターミナルに py と入力すると、"command not found" エラーが出る。	Python インストールマネージャをインストールしましたか?
	スタートをクリックして "Manage app execution aliases" を開き、"Python (default)" のエイリアスが有効であることを確認してください。 既に有効であれば、無効にしてから再度有効にし、コマンドを更新してみてください。 "Python (default windowed)" と "Python install manager" のコマンドも更新が必要かもしれません。
	PATH 変数に %UserProfile%\AppData\Local\Microsoft\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 で変更: 実行ファイルと同じディレクトリにある pythonXX.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 または %ProgramFiles(x86)%\Python X.Y
DefaultJustForMeTargetDir	自分一人用インストールのためのデフォルトインストール先ディレクトリ。	%LocalAppData%\Programs\Python\PythonXY または %LocalAppData%\Programs\Python\PythonXY-32 または %LocalAppData%\Programs\Python\PythonXY-64
DefaultCustomTargetDir	カスタムインストールディレクトリとしてデフォルトで GUI に表示される値。	(空)
AssociateFiles	ランチャもインストールする場合に、ファイルの関連付けを行う。	1
CompileAll	すべての .py ファイルをバイトコンパイルして .pyc を作る。	0
PrependPath	PATH にインストールディレクトリと Scripts ディレクトリを先頭に追加し、 PATHEXT に .PY を追加する。	0
AppendPath	PATH の末尾にインストールディレクトリと Scripts ディレクトリを追加し、PATHEXT に .PY を追加する。	0
Shortcuts	インストールするインタプリタ、ドキュメント、IDLE へのショートカットを作る。	1
Include_doc	Python マニュアルをインストールする。	1
Include_debug	デバッグバイナリをインストールする。	0
Include_dev	開発者用ヘッダーとライブラリをインストールする。これを省略すると、使用不可能なインストールになる可能性があります。	1
Include_exe	python.exe と関連するファイルをインストールする。これを省略すると、使用不可能なインストールになる可能性があります。	1
Include_launcher	Python インストールマネージャ をインストールする。	1
InstallLauncherAllUsers	すべてのユーザーにランチャーをインストールする。 Include_launcher が 1 に設定されている必要があります。	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 が必要ですが、見つかりませんでした。