4. Windows で Python を使う

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

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

To obtain Python from the CPython team, use the Python install manager. This is a standalone tool that makes Python available as global commands on your Windows machine, integrates with the system, and supports updates over time. You can download the Python install manager from python.org/downloads or through the Microsoft Store app.

Once you have installed the Python install manager, the global python command can be used from any terminal to launch your current latest version of Python. This version may change over time as you add or remove different versions, and the py list command will show which is current.

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

If the python or py commands do not seem to be working, see the Troubleshooting section below. There are sometimes additional manual steps required to configure your 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 と入力すると使い始められます。

To install the file downloaded from python.org, either double-click and select "Install", or run Add-AppxPackage <path to MSIX> in Windows PowerShell.

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

When you first install a runtime, you will likely be prompted to add a directory to your PATH. This is optional, if you prefer to use the py command, but is offered for those who prefer the full range of aliases (such as python3.14.exe) to be available. The directory will be %LocalAppData%\Python\bin by default, but may be customized by an administrator. Click Start and search for "Edit environment variables for your account" for the system settings page to add the path.

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

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

If you are not able to install an MSIX in your context, for example, you are using automated deployment software that does not support it, or are targeting Windows Server 2019, see 高度なインストール below for more information.

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.14 ...
$> 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 の指定は任意) をフィルタとして追加でき、それぞれに接頭辞 <、<=、>=、> を付けて範囲を制限できます。

A range of formats are supported, and can be passed as the --format=<FMT> or -f <FMT> option. Formats include table (a user-friendly table view), csv (comma-separated table), json (a single JSON blob), jsonl (one JSON blob per result), exe (just the executable path), prefix (just the prefix path).

--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.14

For compatibility with the old launcher, the --list, --list-paths, -0 and -0p commands (for example, py -0p) are retained. They do not allow additional options, and will produce legacy-formatted output.

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

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

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

CPython publishes multiple runtime variants. For most users, PythonCore is recommended and provides the standard CPython runtime. Tags without any prefix are treated as PythonCore\<TAG>.

PythonTest includes the standard runtime together with the test suite and debugging symbols. It is intended for contributors or users who need these additional files for testing or debugging 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.

To see the available runtime variants, run:

py list --online

To install a specific variant, include it in the tag passed to py install:

py install PythonTest\3.14

--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 を渡すと、出力とログを生成しますが、インストールは一切変更しません。

Passing --refresh will update all registrations for installed runtimes. This will recreate Start menu shortcuts, registry keys, and global aliases (such as python3.14.exe or for any installed scripts). These are automatically refreshed on installation of any runtime, but may need to be manually refreshed after installing packages.

上記のオプションに加えて、--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	The preferred default platform to launch or install. This is treated as a suffix to the specified tag, such that py -V:3.14 would prefer an install for 3.14-64 if it exists (and default_platform is -64), but will use 3.14 if no tagged install exists.
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	(なし)	Specify the directory where global commands (such as python3.14.exe and pip.exe) are stored. This directory should be added to your PATH to make the commands available from your terminal.
download_dir	(なし)	ダウンロードしたファイルを格納するディレクトリを指定します。 このディレクトリは一時的なキャッシュで、ときどきクリーンアップできます。

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

4.1.9. シェバン行

If the first line of a script file starts with #!, it is known as a "shebang" line. Linux and other Unix-like operating systems have native support for such lines and they are commonly used on such systems to indicate how a script should be executed. The python and py commands allow the same facilities to be used with Python scripts on Windows.

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 設定オプションで無効にできます。

Shebang lines that do not match any of the patterns are treated as Windows executable paths that are absolute or relative to the directory containing the script file. This is a convenience for Windows-only scripts, such as those generated by an installer, since the behavior is not compatible with Unix-style shells. These paths may be quoted, and may include multiple arguments, after which the path to the script and any additional arguments will be appended. This functionality may be disabled by the shebang_can_run_anything configuration option.

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 クラス、または使用している展開ツールのドキュメントやサポートを調べることをお勧めします。

Regardless of the install method, users will still need to install their own copies of Python itself, as there is no way to trigger those installs without being a logged-in user. When using the MSIX, the latest version of Python will be available for all users to install without network access.

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	Comma-separated list of shortcut kinds to allow (for example, "pep514,start"). Enabled shortcuts may still be disabled by disable_shortcut_kinds.
install.disable_shortcut_kinds	Comma-separated list of shortcut kinds to exclude (for example, "pep514,start"). Disabled shortcuts are not reactivated by 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.14t
$> py install 3.14t-arm64
$> py install 3.14t-32

This will install and register as normal. If you have no other runtimes installed, then python will launch this one. Otherwise, you will need to use py -V:3.14t or, if you have added the global aliases directory to your PATH environment variable, the python3.14t.exe commands.

4.1.13. インデックスの署名

Added in version 26.2.

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

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

As well as requiring a valid signature, the required_root_subject and required_publisher_subject settings can further restrict acceptable signatures based on the certificate Subject fields. Any attribute specified in the configuration must match the attribute in the certificate (additional attributes in the certificate are ignored). Typical attributes are CN= for the common name, O= for the organization, and C= for the publisher's country.

最後に、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. トラブルシューティング

If your Python install manager does not seem to be working correctly, work through these tests and fixes to see if it helps. If not, report an issue at our bug tracker, including any relevant log files (written to your %TEMP% directory by default).

トラブルシューティング

症状	試すこと
ターミナルに 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.14-embed --target=<directory>

When extracted, the embedded distribution is (almost) fully isolated from the user's system, including environment variables, system registry settings, and installed packages. The standard library is included as pre-compiled and optimized .pyc files in a ZIP, and python3.dll, python314.dll, python.exe and pythonw.exe are all provided. Tcl/Tk (including all dependents, such as IDLE), pip and the Python documentation are not included.

デフォルトの ._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 インタープリタを提供できます。

As with the application use, packages can be installed to any location as there is an opportunity to specify search paths before initializing the interpreter. Otherwise, there are no fundamental differences between using the embedded distribution and a regular installation.

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 システムでは、ビルド間でファイルを保持しない場合、この作業を自動的に行います。

Alongside the tools directory is a build\native directory. This contains an MSBuild properties file python.props that can be used in a C++ project to reference the Python install. Including the settings will automatically use the headers and import libraries in your build.

The package information pages on nuget.org are www.nuget.org/packages/python for the 64-bit version, www.nuget.org/packages/pythonx86 for the 32-bit version, and www.nuget.org/packages/pythonarm64 for the ARM64 version.

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

Added in version 3.13.

Packages containing free-threaded binaries are named python-freethreaded for the 64-bit version, pythonx86-freethreaded for the 32-bit version, and pythonarm64-freethreaded for the ARM64 version. These packages contain both the python3.14t.exe and python.exe entry points, both of which run free-threaded.

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 のバージョン

As specified in PEP 11, a Python release only supports a Windows platform while Microsoft considers the platform under extended support. This means that Python 3.14 supports Windows 10 and newer. If you require Windows 7 support, install Python 3.8. If you require Windows 8.1 support, install 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.

Windows still uses legacy encodings for the system encoding (the ANSI Code Page). Python uses it for the default encoding of text files (e.g. locale.getencoding()).

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

You can use the Python UTF-8 Mode to change the default text encoding to UTF-8. You can enable the Python UTF-8 Mode via the -X utf8 command line option, or the PYTHONUTF8=1 environment variable. See PYTHONUTF8 for enabling UTF-8 mode, and Python インストールマネージャ for how to modify environment variables.

When the Python UTF-8 Mode is enabled, you can still use the system encoding (the ANSI Code Page) via the "mbcs" codec.

Note that adding PYTHONUTF8=1 to the default environment variables will affect all Python 3.7+ applications on your system. If you have any Python 3.7+ applications which rely on the legacy system encoding, it is recommended to set the environment variable temporarily or use the -X utf8 command line option.

注釈

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

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

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

4.8. モジュールの検索

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

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

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

• If the environment variable PYTHONPATH exists, as described in 環境変数, its entries are added next. Note that on Windows, paths in this variable must be separated by semicolons, to distinguish them from the colon used in drive identifiers (such as C:\).

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

• If the environment variable PYTHONHOME is set, it is assumed as "Python Home". Otherwise, the path of the main Python executable is used to locate a "landmark file" (either Lib\os.py or pythonXY.zip) to deduce the "Python Home". If a Python home is found, the relevant sub-directories added to sys.path (such as Lib and plat-win) are based on that folder. Otherwise, the core Python path is constructed from the PythonPath stored in the registry.

• If the Python Home cannot be located, no PYTHONPATH is specified in the environment, and no registry entries can be found, a default path with relative entries is used (for example, .\Lib;.\plat-win).

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

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

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

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

• When Python is hosted in another .exe (for example, in a different directory or embedded via COM), the "Python Home" will not be deduced, so the core path from the registry is used. Other "application paths" in the registry are always read.

• If Python can't find its home and there are no registry values (frozen .exe, some very strange installation setup) you get a path with some default, but relative, paths.

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

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

• If you are loading python3.dll or python314.dll in your own executable, explicitly set PyConfig.module_search_paths before Py_InitializeFromConfig().

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

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

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

バージョン 3.6 で変更: Add ._pth file support and remove applocal option from pyvenv.cfg.

バージョン 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.14 のインストーラは 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.14) がインストールされている場合は、Python 3.14 が起動することになります。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 が必要ですが、見つかりませんでした。