1. コマンドラインと環境

CPython インタプリタはコマンドラインと環境を読み取って様々な設定を行ないます。

ほかの実装では、コマンドラインの形式が異なる場合があります。 関連情報は 別のPythonの実装 を参照してください。

1.1. コマンドライン

Python を起動するとき、以下のうち任意のオプションを指定できます:

python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]

もちろん、もっとも一般的な利用方法は、単純にスクリプトを起動することです:

python myscript.py

1.1.1. インターフェイスオプション

インタプリタのインターフェイスは UNIX シェルのものに似ていますが、より多くの起動方法を提供しています:

• 標準入力が tty デバイスに接続された状態で起動すると、EOF (ファイル終端文字) を読み込むまで、コマンドの入力を促して実行する処理を繰り返します。 EOF は UNIX では Ctrl-D、Windows では Ctrl-Z, Enter で入力できます。 対話モードについて詳しくは、対話モード を参照してください。

• ファイル名引数か、標準入力としてファイルを渡された場合、そのファイルからスクリプトを読み込んで実行します。

• ディレクトリ名を引数に受け取った場合、そのディレクトリから適切な名前のスクリプトファイルを読み込んで実行します。

• -c command を指定して起動すると、command に指定された Python の文を実行します。 command には、改行で区切って複数の文を指定できます。

• -m module-name を指定して起動すると、標準のインポート機構を使って指定されたモジュールを探し、スクリプトとして実行します。

非インタラクティブモードでは、入力の全体が実行前にパースされます。

インターフェイスオプションは、インタープリタが処理するオプションのリストを終了させます。 それ以降の引数はすべて sys.argv に格納されます。 ただし、添字がゼロの最初の要素 (sys.argv[0]) は、プログラムのソースを表す文字列になります。

-c <command>

command 内の Python コードを実行します。 command には、改行で区切って 1 つ以上の文を指定できます。 通常のモジュールのコードと同様に、行頭の空白文字は意味を持ちます。

このオプションが指定された場合、 sys.argv の最初の要素は "-c" になり、カレントディレクトリが sys.path の先頭に追加されます (そのディレクトリにあるモジュールをトップレベルモジュールとして import 出来るようになります)。

引数 command を指定して 監査イベント cpython.run_command を送出します。

バージョン 3.14 で変更: command は実行前に自動で共通のインデントが取り除かれます。

-m <module-name>

標準のインポート機構を使ってモジュールを探し、その内容を __main__ モジュールとして実行します。

引数は module 名なので、拡張子 (.py) を含めてはいけません。モジュール名は有効な Python の絶対モジュール名 (absolute module name) であるべきですが、実装がそれを強制しているとは限りません (例えば、ハイフンを名前に含める事を許可するかもしれません)。

パッケージ名 (名前空間パッケージも含む) でも構いません。通常のモジュールの代わりにパッケージ名が与えられた場合、インタプリタは <pkg>.__main__ を main モジュールとして実行します。この挙動はスクリプト引数として渡されたディレクトリや zip ファイルをインタプリタが処理するのと意図的に同じにしています。

注釈

このオプションは組み込みモジュールや C で書かれた拡張モジュールには利用できません。 Python モジュールファイルを持っていないからです。しかし、コンパイル済みのモジュールは、たとえ元のソースファイルがなくても利用可能です。

このオプションが指定された場合、 sys.argv の最初の要素はモジュールファイルのフルパスになります (モジュールファイルを検索している間、最初の要素は "-m" に設定されます)。 -c オプションと同様に、カレントディレクトリが sys.path の先頭に追加されます。

-I オプションを使うと、sys.path にカレントディレクトリもユーザーの site-packages ディレクトリも含まれない隔離モードで、スクリプトを実行できます。 すべての PYTHON* 環境変数も無視されます。

多くの標準ライブラリモジュールにはスクリプトとして実行された時のためのコードがあります。例えば、 timeit モジュールは次のように実行可能です:

python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # 詳細を表示

引数 module-name を指定して 監査イベント cpython.run_module を送出します。

参考

runpy.run_module()

Python コードで直接使える等価な機能

PEP 338 - モジュールをスクリプトとして実行する

バージョン 3.1 で変更: パッケージ名を指定して __main__ サブモジュールを実行できるようになりました。

バージョン 3.4 で変更: 名前空間パッケージもサポートされました

-

標準入力 (sys.stdin) からコマンドを読み込みます。標準入力がターミナルだった場合、暗黙的に -i オプションが指定されます。

このオプションが指定された場合、 sys.argv の最初の要素は "-" で、カレントディレクトリが sys.path の先頭に追加されます。

引数無しで 監査イベント cpython.run_stdin を送出します。

<script>

script 内の Python コードを実行します。 script は、Python ファイル、 __main__.py ファイルがあるディレクトリ、 __main__.py ファイルがある zip ファイルのいずれかの、ファイルシステム上の (絶対または相対) パスでなければなりません。

このオプションが指定された場合、 sys.argv の最初の要素はコマンドラインで指定されたスクリプト名になります。

スクリプト名が Python ファイルを直接指定していた場合、そのファイルを含むディレクトリが sys.path の先頭に追加され、そのファイルは __main__ モジュールとして実行されます。

スクリプト名がディレクトリまたは zip ファイルを指す場合、スクリプト名が sys.path の先頭に追加され、その場所にある __main__.py ファイルが __main__ モジュールとして実行されます。

-I オプションを使うと、sys.path にスクリプトのディレクトリもユーザーの site-packages ディレクトリも含まれない隔離モードで、スクリプトを実行できます。 すべての PYTHON* 環境変数も無視されます。

引数 filename を指定して 監査イベント cpython.run_file を送出します。

参考

runpy.run_path()

Python コードで直接使える等価な機能

インターフェイスオプションが与えられなかった場合、-i が暗黙的に指定され、sys.argv[0] が空の文字列 ("") になり、 現在のディレクトリが sys.path の先頭に追加されます。また、利用可能であればタブ補完と履歴編集が自動的に有効化されます (readline の設定 を参照してください)。

参考

インタープリタを起動する

バージョン 3.4 で変更: タブ補完と履歴の編集が自動的に有効化されます。

1.1.2. 一般オプション

-?

-h

--help

すべてのコマンドラインオプションと、それぞれに対応する環境変数の短い説明を表示して終了します。

--help-env

Python 固有の環境変数の短い説明を表示して終了します。

Added in version 3.11.

--help-xoptions

実装固有の -X オプションの説明を表示して終了します。

Added in version 3.11.

--help-all

使用方法のすべての情報を表示して終了します。

Added in version 3.11.

-V

--version

Python のバージョン番号を表示して終了します。出力の例:

Python 3.8.0b2+

2つ指定すると、次のようにより多くのビルドの情報を表示します:

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

Added in version 3.6: -VV オプション。

1.1.3. その他のオプション

-b

エンコーディングを指定せずに bytes または bytearray を str に変換した場合、bytes または bytearray を str と比較した場合、あるいは bytes を int と比較した場合に、警告を出します。 オプションを 2 回指定した場合 (-bb) は、エラーを発生させます。

バージョン 3.5 で変更: bytes と int の比較にも影響するようになりました。

バージョン 3.15 で非推奨: -b と -bb コマンドラインオプションは非推奨となり、Python 3.17 では何も行わなくなる予定です。 これらは主に Python 2 から 3 への移行を補助するためのものでした。 Python 3.17 以降、これらの場合に BytesWarning は発生しなくなります。 代わりに型チェッカーを使ってください。

-B

与えられた場合、Python はソースモジュールのインポート時に .pyc ファイルの作成を試みません。 PYTHONDONTWRITEBYTECODE 環境変数も参照してください。

--check-hash-based-pycs default|always|never

ハッシュベースの .pyc ファイルの検証方法を制御します。 キャッシュされたバイトコードの無効化 を参照してください。 default に設定した場合、検証付きと検証なしのハッシュベースのバイトコードキャッシュファイルは、それぞれのデフォルトの意味に従って検証されます。 always に設定した場合、すべてのハッシュベースの .pyc ファイルが、検証付きか検証なしかにかかわらず、対応するソースファイルと照合されます。 never に設定した場合、ハッシュベースの .pyc ファイルは、対応するソースファイルと照合されません。

タイムスタンプベースの .pyc ファイルの扱いは、このオプションの影響を受けません。

-d

パーサのデバッグ出力を有効にします (上級者向け)。 PYTHONDEBUG 環境変数も参照してください。

このオプションには Python のデバッグビルド が必要で、それ以外では無視されます。

-E

PYTHONPATH や PYTHONHOME など、設定されているすべての PYTHON* 環境変数を無視します。

-P および -I (隔離モード) オプションも参照してください。

-i

実行後に対話モードに入ります。

-i オプションを使うと、次のいずれの場合にも対話モードに入ります:

• 最初の引数としてスクリプトが渡された場合

• -c オプションを使用した場合

• -m オプションを使用した場合

sys.stdin がターミナルでないと判断された場合でも、対話モードが開始します。 PYTHONSTARTUP ファイルは読み込まれません。

このオプションはグローバル変数や、スクリプトが例外を発生させるときにそのスタックトレースを調べるのに便利です。 PYTHONINSPECT も参照してください。

-I

Python を隔離モードで実行します。-E、-P、および -s オプションも暗黙的に指定されます。

隔離モードでは、sys.path にスクリプトのディレクトリもユーザーの site-packages ディレクトリも含まれません。 すべての PYTHON* 環境変数も無視されます。 ユーザーによる悪意のあるコードの注入を防ぐため、さらに制限が課される場合もあります。

Added in version 3.4.

-O

assert 文と、__debug__ の値を条件とするコードを取り除きます。 コンパイル済み (バイトコード) ファイルの名前は、.pyc 拡張子の前に .opt-1 を追加したものになります (PEP 488 を参照)。 PYTHONOPTIMIZE も参照してください。

バージョン 3.5 で変更: PEP 488 に従って .pyc ファイル名を変更します。

-OO

-O の処理に加えて、ドキュメンテーション文字列も取り除きます。 コンパイル済み (バイトコード) ファイルの名前は、.pyc 拡張子の前に .opt-2 を追加したものになります (PEP 488 を参照)。

バージョン 3.5 で変更: PEP 488 に従って .pyc ファイル名を変更します。

-P

安全でない可能性のあるパスを sys.path の先頭に追加しません:

• コマンドラインが python -m module の場合、カレント作業ディレクトリを先頭に追加しません。

• コマンドラインが python script.py の場合、スクリプトのディレクトリを先頭に追加しません。 スクリプトがシンボリックリンクの場合は、シンボリックリンクを解決します。

• コマンドラインが python -c code または python (REPL) の場合、カレント作業ディレクトリを意味する空文字列を先頭に追加しません。

PYTHONSAFEPATH 環境変数と、-E および -I (隔離モード) オプションも参照してください。

Added in version 3.11.

-q

インタラクティブモードでも copyright とバージョンのメッセージを表示しません。

Added in version 3.2.

-R

ハッシュのランダム化を有効にします。 ハッシュのランダム化はデフォルトで有効なため、このオプションは PYTHONHASHSEED 環境変数が random 以外の値に設定されている場合にのみ効果があります。

以前のバージョンの Python では、このオプションはハッシュのランダム化を有効にし、str オブジェクトと bytes オブジェクトの __hash__() の値に、予測不能なランダムな値による「ソルト」を加えます。 ハッシュ値は、個々の Python プロセス内では一定ですが、Python を起動し直した場合の値を予測することはできません。

ハッシュのランダム化は、辞書の構築時の最悪の計算量 O(n²) を悪用するように選ばれた入力によって、サービス拒否が発生するのを防ぐためのものです。 詳細は https://ocert.org/advisories/ocert-2011-003.html を参照してください。

PYTHONHASHSEED を使うと、ハッシュのシードに使う秘密の値を固定値に設定できます。

Added in version 3.2.3.

バージョン 3.7 で変更: このオプションが無視されなくなりました.

-s

ユーザのサイトパッケージのディレクトリ を sys.path に追加しません。

PYTHONNOUSERSITE も参照してください。

参考

PEP 370 -- ユーザごとの site-packages ディレクトリ

-S

site モジュールの import と、そのモジュールが行なっていた site ごとの sys.path への操作を無効にします。後で site を明示的に import しても、これらの操作は実行されません (実行したい場合は、 site.main() を呼び出してください)。

-u

stdout と stderr のストリームでバッファリングを行わないように強制します。 このオプションは stdin ストリームには影響しません。

PYTHONUNBUFFERED も参照してください。

バージョン 3.7 で変更: stdout と stderr のストリームのテキスト層で、バッファリングを行わなくなりました。

-v

モジュールが初期化されるたびにメッセージを出力し、それがどこ (ファイル名やビルトインモジュール) からロードされたのかを表示します。 二回与えられた場合 (-vv) は、モジュールを検索するときにチェックしたファイルごとにメッセージを出力します。また、終了時のモジュールクリーンアップに関する情報も提供します。

バージョン 3.10 で変更: site モジュールが、処理中のサイト固有のパスと .pth ファイルを報告するようになりました。

PYTHONVERBOSE も参照してください。

-W arg

警告制御。 Python の警告機構はデフォルトでは警告メッセージを sys.stderr に表示します。

最も単純な設定では、プロセスが出すすべての警告に、特定のアクションを無条件で適用します (通常はデフォルトで無視される警告も対象です)。

-Wdefault  # 呼び出し箇所ごとに一度警告
-Werror    # 例外に変換
-Walways   # 毎回警告
-Wall      # -Walways と同じ
-Wmodule   # 呼び出し元モジュールごとに一度警告
-Wonce     # Python プロセスごとに一度警告
-Wignore   # 警告しない

アクション名は任意の長さに省略でき、インタープリタが適切なアクション名に解決します。 例えば、-Wi は -Wignore と同じです。

引数の完全形は次のようになります:

action:message:category:module:lineno

空のフィールドはすべての値にマッチします。 末尾の空のフィールドは省略できます。 例えば、-W ignore::DeprecationWarning はすべての DeprecationWarning 警告を無視します。

action フィールドは前述のとおりですが、残りのフィールドにマッチする警告にだけ適用されます。

message フィールドは、警告メッセージの先頭とマッチする必要があります。 このマッチでは大文字と小文字を区別しません。 スラッシュ (/) で始まり、スラッシュで終わる場合は正規表現を指定し、それ以外の場合はリテラル文字列を指定します。

category フィールドは警告カテゴリ (例: DeprecationWarning) とマッチします。 このフィールドにはクラス名を指定する必要があります。 メッセージの実際の警告カテゴリが、指定した警告カテゴリのサブクラスかどうかが調べられます。

module フィールドは、完全修飾されたモジュール名とマッチします。 このマッチでは大文字と小文字を区別します。 スラッシュ (/) で始まり、スラッシュで終わる場合は、完全修飾されたモジュール名の先頭がマッチする必要のある正規表現を指定します。 それ以外の場合は、完全修飾されたモジュール名と等しくなければならないリテラル文字列を指定します。

lineno フィールドは行番号とマッチします。 ゼロはすべての行番号にマッチするため、行番号を省略した場合と同じです。

複数の -W オプションを指定できます。 警告が複数のオプションにマッチした場合は、最後にマッチしたオプションのアクションが実行されます。 不正な -W オプションは無視されます (ただし、最初の警告が出される際に、不正なオプションについての警告メッセージが表示されます)。

警告は PYTHONWARNINGS 環境変数や、Python プログラム内から warnings モジュールを使って制御することもできます。 例えば、warnings.filterwarnings() 関数を使うと、警告メッセージに対して正規表現を使用できます。

詳しくは 警告フィルタ と 警告フィルタの指定方法 を参照してください。

バージョン 3.15 で変更: message と module で正規表現が使えるようになりました。

-x

ソースの最初の行を読み飛ばし、Unix 以外の形式の #!cmd を使用できるようにします。

このオプションを使うと、Python スクリプトを Windows のバッチファイルにできます。 Unix で shebang 行を追加して実行可能ビットを設定するのと同じように、Python スクリプトの拡張子を .bat に変更し、スクリプトの先頭に次の行を追加できます:

@py -x "%~f0" %* & exit /b

Python インタープリタのパスを明示的に指定する場合は、次のようにします:

@"C:\Path\to\python.exe" -x "%~f0" %* & exit /b

Python のコメントである shebang 行とは異なり、この行は Python の有効な構文ではないため、読み飛ばすには -x オプションが必要です。

-X

様々な実装固有のオプションのために予約されています。現在のところ CPython は以下の値を定義しています:

• -X faulthandler は faulthandler を有効にします。 PYTHONFAULTHANDLER も参照してください。

  Added in version 3.3.

• -X showrefcount は、プログラムの終了時、または対話的インタープリタでの各文の実行後に、参照カウントの合計と使用中のメモリブロック数を出力します。 デバッグビルド でのみ動作します。

  Added in version 3.4.

• -X tracemalloc は、tracemalloc モジュールを使って Python のメモリ割り当ての追跡を開始します。 デフォルトでは、追跡結果のトレースバックには最新のフレームのみが保存されます。 トレースバックを最大 NFRAME フレームに制限して追跡を開始するには、-X tracemalloc=NFRAME を使います。 詳細は tracemalloc.start() と PYTHONTRACEMALLOC を参照してください。

  Added in version 3.4.

• -X int_max_str_digits は 整数と文字列の間の変換の長さ制限 を設定します。 PYTHONINTMAXSTRDIGITS も参照してください。

  Added in version 3.11.

• -X importtime は、各インポートにかかる時間を表示します。 モジュール名、累積時間 (ネストされたインポートを含む)、自身の処理時間 (ネストされたインポートを除く) を表示します。 マルチスレッドのアプリケーションでは、出力が崩れる場合があります。 典型的な使い方は python -X importtime -c 'import asyncio' です。

  -X importtime=2 は、インポートされたモジュールがすでに読み込まれている場合に、そのことを示す追加の出力を有効にします。 この場合、両方の時間の列に文字列 cached が表示されます。

  PYTHONPROFILEIMPORTTIME も参照してください。

  Added in version 3.7.

  バージョン 3.14 で変更: 読み込み済みのモジュールのインポートも追跡する -X importtime=2 を追加し、1 と 2 以外の値を将来のために予約しました。

• -X dev は Python 開発モード を有効にします。 このモードでは、負荷が大きいためデフォルトでは有効にできない追加の実行時チェックを行います。 PYTHONDEVMODE も参照してください。

  Added in version 3.7.

• -X utf8 は Python UTF-8 モード を有効にします。 -X utf8=0 は、通常なら自動で有効になる場合でも、Python UTF-8 モード を明示的に無効にします。 PYTHONUTF8 も参照してください。

  Added in version 3.7.

• -X pycache_prefix=PATH は、コードツリー内ではなく、指定したディレクトリをルートとする対応する別のツリー内に .pyc ファイルを書き込むようにします。 PYTHONPYCACHEPREFIX も参照してください。

  Added in version 3.8.

• -X warn_default_encoding は、ファイルを開く際にロケール固有のデフォルトのエンコーディングが使われると、EncodingWarning を発生させます。 PYTHONWARNDEFAULTENCODING も参照してください。

  Added in version 3.10.

• -X no_debug_ranges は、コードオブジェクトの各命令に追加の位置情報 (終了行、開始列のオフセット、終了列のオフセット) を対応付けるテーブルを含めないようにします。 これは、コードオブジェクトや pyc ファイルを小さくしたい場合や、インタープリタがトレースバックを表示する際に追加の位置を示す表示を抑制したい場合に役立ちます。 PYTHONNODEBUGRANGES も参照してください。

  Added in version 3.11.

• -X frozen_modules determines whether or not frozen modules are ignored by the import machinery. A value of on means they get imported and off means they are ignored. The default is on if this is an installed Python (the normal case). If it's under development (running from the source tree) then the default is off. Note that the importlib_bootstrap and importlib_bootstrap_external frozen modules are always used, even if this flag is set to off. See also PYTHON_FROZEN_MODULES.

  Added in version 3.11.

• -X perf は、Linux の perf プロファイラのサポートを有効にします。 このオプションを指定すると、perf プロファイラが Python の呼び出しを報告できるようになります。 このオプションは一部のプラットフォームでのみ利用でき、現在のシステムでサポートされていない場合は何も行いません。 デフォルトの値は "off" です。 PYTHONPERFSUPPORT と perf map 対応プロファイラのための Python のサポート も参照してください。

  Added in version 3.12.

• -X perf_jit は、DWARF に対応した Linux の perf プロファイラのサポートを有効にします。 このオプションを指定すると、perf プロファイラが DWARF 情報を使って Python の呼び出しを報告できるようになります。 このオプションは一部のプラットフォームでのみ利用でき、現在のシステムでサポートされていない場合は何も行いません。 デフォルトの値は "off" です。 PYTHON_PERF_JIT_SUPPORT と perf map 対応プロファイラのための Python のサポート も参照してください。

  Added in version 3.13.

• -X disable-remote-debug は、PEP 768 で説明されているリモートデバッグのサポートを無効にします。 これには、別のプロセスでのコード実行を予約する機能と、現在のプロセスで実行するコードを受け取る機能の両方が含まれます。

  このオプションは一部のプラットフォームでのみ利用でき、現在のシステムでサポートされていない場合は何も行いません。 PYTHON_DISABLE_REMOTE_DEBUG と PEP 768 も参照してください。

  Added in version 3.14.

• -X cpu_count=n は os.cpu_count()、os.process_cpu_count()、multiprocessing.cpu_count() を上書きします。 n は 1 以上でなければなりません。 このオプションは、コンテナシステムの CPU リソースを制限する必要がある場合に役立つことがあります。 PYTHON_CPU_COUNT も参照してください。 n が default の場合、上書きは行われません。

  Added in version 3.13.

• -X presite=module または -X presite=module:func は、site モジュールの実行前、かつ __main__ モジュールが存在する前に実行するエントリーポイントを指定します。 したがって、インポートされたモジュールは __main__ ではありません。 これは、Python の初期化の早い段階でコードを実行するために使用できます。 このオプションを利用するには、Python が デバッグモードでビルド されている必要があります。 PYTHON_PRESITE も参照してください。

  バージョン 3.15 で変更: エントリーポイントの形式として module:func も受け付けるようになりました。

  Added in version 3.13.

• -X gil=0,1 は、それぞれ GIL を強制的に無効または有効にします。 0 への設定は、--disable-gil を指定して構成したビルドでのみ利用できます。 PYTHON_GIL と フリースレッドの CPython も参照してください。

  Added in version 3.13.

• -X thread_inherit_context=0,1 を 1 に設定すると、Thread はデフォルトで、Thread.start() の呼び出し元のコンテキストのコピーを使ってスレッドを開始します。 それ以外の場合、スレッドは空のコンテキストで開始します。 未設定の場合、このオプションのデフォルト値は、フリースレッドビルドでは 1、それ以外では 0 です。 PYTHON_THREAD_INHERIT_CONTEXT も参照してください。

  Added in version 3.14.

• -X context_aware_warnings=0,1 を 1 に設定すると、warnings.catch_warnings コンテキストマネージャは、警告フィルタの状態の保存に ContextVar を使います。 未設定の場合、このオプションのデフォルト値は、フリースレッドビルドでは 1、それ以外では 0 です。 PYTHON_CONTEXT_AWARE_WARNINGS も参照してください。

  Added in version 3.14.

• -X pathconfig_warnings=0,1 が真 (1) の場合、sys.path モジュール検索パスの初期化 の際に stderr に警告を出力できます。 偽 (0) の場合は、これらの警告を抑制します。 デフォルトでは真に設定されます。 PYTHON_PATHCONFIG_WARNINGS も参照してください。

  Added in version 3.15.

• -X tlbc=0,1 は、--disable-gil を指定して構成したビルドで、スレッドローカルなバイトコードを有効 (1、デフォルト) または無効 (0) にします。 無効にすると、特殊化インタープリタも無効になります。 PYTHON_TLBC も参照してください。

  Added in version 3.14.

• -X lazy_imports=all,normal は、遅延インポートの挙動を制御します。 all ではすべてのインポートをデフォルトで遅延させ、normal (デフォルト) はソースコード内の lazy キーワードに従います。 PYTHON_LAZY_IMPORTS も参照してください。

  Added in version 3.15.

任意の値を渡し、 sys._xoptions 辞書から取り出すことも出来ます。

Added in version 3.2.

バージョン 3.9 で変更: -X showalloccount オプションは削除されました。

バージョン 3.10 で変更: -X oldparser オプションは削除されました。

Removed in version 3.14: -J は Jython 用に予約されなくなり、特別な意味を持たなくなりました。

1.1.4. 色の制御

デフォルトでは、 Python インタープリターは、トレースバックの表示などの特定の状況で、出力を色でハイライトするように構成されています。この振る舞いは、異なる環境変数を設定することで制御できます。

環境変数 TERM を dumb に設定することで、色付けを無効にできます。

FORCE_COLOR 環境変数が設定されている場合、 TERM の値にかかわらず、色付けは有効になります。これは、ターミナルではないが ANSI エスケープシーケンスを表示できる CI システムで有効です。

NO_COLOR 環境変数が設定されている場合、 Python は出力のすべての色を無効にします。これは FORCE_COLOR よりも優先されます。

これらのすべての環境変数は、色の出力の制御のために他のツールにも使用されます。 Python インタープリターでのみ色の出力を制御するには、 PYTHON_COLORS 環境変数を使用できます。この変数は、 FORCE_COLOR よりも優先される NO_COLOR よりも、さらに優先されます。

1.2. 環境変数

以下の環境変数は Python の挙動に影響します。環境変数は -E や -I 以外のコマンドラインスイッチの前に処理されます。衝突したときにコマンドラインスイッチが環境変数をオーバーライドするのは慣例です。

PYTHONHOME

標準 Python ライブラリの場所を変更します。デフォルトでは、ライブラリは prefix/lib/pythonversion と exec_prefix/lib/pythonversion から検索されます。ここで、 prefix と exec_prefix はインストール依存のディレクトリで、両方共デフォルトでは /usr/local です。

PYTHONHOME が1つのディレクトリに設定されている場合、その値は prefix と exec_prefix の両方を置き換えます。それらに別々の値を指定したい場合は、 PYTHONHOME を prefix:exec_prefix のように指定します。

PYTHONPATH

モジュールファイルのデフォルトの検索パスを追加します。この環境変数のフォーマットはシェルの PATH と同じで、 os.pathsep (Unix ならコロン、 Windows ならセミコロン) で区切られた1つ以上のディレクトリパスです。存在しないディレクトリは警告なしに無視されます。

通常のディレクトリに加えて、 PYTHONPATH のエントリはピュアPython モジュール(ソース形式でもコンパイルされた形式でも) を含む zip ファイルを参照することもできます。拡張モジュールは zip ファイルの中から import することはできません。

デフォルトの検索パスはインストール依存ですが、通常は prefix/lib/pythonversion で始まります。 (上の PYTHONHOME を参照してください。) これは 常に PYTHONPATH に追加されます。

上の インターフェイスオプション で説明されているように、追加の検索パスディレクトリが PYTHONPATH の手前に追加されます。検索パスは Python プログラムから sys.path 変数として操作することができます。

PYTHONSAFEPATH

空でない文字列を設定すると、安全でない可能性のあるパスを sys.path の先頭に追加しなくなります。 詳細は -P オプションを参照してください。

Added in version 3.11.

PYTHONPLATLIBDIR

空でない文字列を設定すると、sys.platlibdir の値を上書きします。

Added in version 3.9.

PYTHONSTARTUP

この変数が読み込み可能なファイル名の場合、対話モードで最初のプロンプトが表示される前にそのファイルの Python コマンドが実行されます。 ファイル内で定義されているオブジェクトやインポートされたオブジェクトを対話セッションで修飾せずに使用するために、ファイルは対話的なコマンドと同じ名前空間で実行されます。 このファイルの中で、プロンプト sys.ps1 や sys.ps2、ならびにフック sys.__interactivehook__ も変更できます。

起動時に呼び出されると、ファイル名を引数として 監査イベント cpython.run_startup を送出します。

PYTHONOPTIMIZE

この変数に空でない文字列を設定するのは -O オプションを指定するのと等価です。整数を設定した場合、 -O を複数回指定したのと同じになります。

PYTHONBREAKPOINT

設定する場合は、ドット区切りのパス表記で呼び出し可能オブジェクトを指定します。 そのオブジェクトを含むモジュールがインポートされ、続いて sys.breakpointhook() のデフォルト実装によってそのオブジェクトが呼び出されます。 このフック自体は、組み込みの breakpoint() から呼び出されます。 未設定の場合、または空文字列に設定した場合は、値 "pdb.set_trace" を指定した場合と同じです。 文字列 "0" を設定すると、sys.breakpointhook() のデフォルト実装は何も行わず、直ちに戻ります。

Added in version 3.7.

PYTHONDEBUG

この変数に空でない文字列を設定するのは -d オプションを指定するのと等価です。整数を指定した場合、 -d を複数回指定したのと同じになります。

この環境変数には Python のデバッグビルド が必要で、それ以外では無視されます。

PYTHONINSPECT

この変数に空でない文字列を設定するのは -i オプションを指定するのと等価です。

この変数は Python コードから os.environ を使って変更して、プログラム終了時のインスペクトモードを強制することができます。

引数無しで 監査イベント cpython.run_stdin を送出します。

バージョン 3.12.5 で変更: (3.11.10、3.10.15、3.9.20、3.8.20 も同様) 監査イベントを送出するようになりました。

バージョン 3.13 で変更: 可能な場合は PyREPL を使用するようになり、その場合は PYTHONSTARTUP も実行されます。 監査イベントを送出するようになりました。

PYTHONUNBUFFERED

この変数に空でない文字列を設定するのは -u オプションを指定するのと等価です。

PYTHONVERBOSE

この変数に空でない文字列を設定するのは -v オプションを指定するのと等価です。整数を設定した場合、 -v を複数回指定したのと同じになります。

PYTHONCASEOK

この環境変数が設定されている場合、 Python は import 文で大文字/小文字を区別しません。 これは Windows と macOS でのみ動作します。

PYTHONDONTWRITEBYTECODE

この変数に空でない文字列を設定した場合、 Python はソースモジュールのインポート時に .pyc ファイルを作成しようとはしなくなります。 -B オプションを指定するのと等価です。

PYTHONPYCACHEPREFIX

設定すると、Python はソースツリー内の __pycache__ ディレクトリではなく、このパスを起点としてソースツリーに対応するディレクトリツリー内に .pyc ファイルを書き込みます。 -X pycache_prefix=PATH オプションの指定と同じです。

Added in version 3.8.

PYTHONHASHSEED

この変数が設定されていない場合や random に設定された場合、乱数値が str、bytes オブジェクトのハッシュのシードに使われます。

PYTHONHASHSEED が整数値に設定された場合、その値はハッシュランダム化が扱う型の hash() 生成の固定シードに使われます。

その目的は再現性のあるハッシュを可能にすることです。例えばインタープリタ自身の自己テストや Python プロセスのクラスタでハッシュ値を共有するのに用います。

整数は [0,4294967295] の十進数でなければなりません。0 を指定するとハッシュランダム化は無効化されます。

Added in version 3.2.3.

PYTHONINTMAXSTRDIGITS

整数を設定すると、インタープリタ全体の 整数と文字列の間の変換の長さ制限 を設定するために使われます。

Added in version 3.11.

PYTHONIOENCODING

この変数がインタープリタ実行前に設定されていた場合、encodingname:errorhandler という文法で標準入力/標準出力/標準エラー出力のエンコードを上書きします。 encodingname と :errorhandler の部分はどちらも任意で、str.encode() と同じ意味を持ちます。

標準エラー出力の場合、:errorhandler の部分は無視されます; ハンドラは常に 'backslashreplace' です。

バージョン 3.4 で変更: encodingname の部分が任意になりました。

バージョン 3.6 で変更: Windows では、PYTHONLEGACYWINDOWSSTDIO も指定しない限り、この変数で指定したエンコーディングは対話型コンソールのバッファに対しては無視されます。 標準ストリームでリダイレクトされたファイルやパイプは、この制限の影響を受けません。

PYTHONNOUSERSITE

-s オプションと同じです。 設定すると、Python は ユーザーの site-packages ディレクトリ を sys.path に追加しなくなります。

参考

PEP 370 -- ユーザごとの site-packages ディレクトリ

PYTHONUSERBASE

ユーザーベースディレクトリ を定義します。 このディレクトリは、ユーザーの site-packages ディレクトリ のパスと、python -m pip install --user の インストール先のパス を求めるために使われます。

ユーザーの site-packages を無効にするには、PYTHONNOUSERSITE または -s オプションを参照してください。

参考

PEP 370 -- ユーザごとの site-packages ディレクトリ

PYTHONEXECUTABLE

この環境変数が設定された場合、 sys.argv[0] に、C ランタイムから取得した値の代わりにこの環境変数の値が設定されます。macOS でのみ動作します。

PYTHONWARNINGS

-W オプションと同じです。 コンマで区切った文字列を設定すると、-W を複数回指定した場合と同じになり、リストの後ろにあるフィルタが前にあるフィルタより優先されます。

最も単純な設定では、プロセスが出すすべての警告に、特定のアクションを無条件で適用します (通常はデフォルトで無視される警告も対象です)。

PYTHONWARNINGS=default  # 呼び出し箇所ごとに一度警告
PYTHONWARNINGS=error    # 例外に変換
PYTHONWARNINGS=always   # 毎回警告
PYTHONWARNINGS=all      # PYTHONWARNINGS=always と同じ
PYTHONWARNINGS=module   # 呼び出し元モジュールごとに一度警告
PYTHONWARNINGS=once     # Python プロセスごとに一度警告
PYTHONWARNINGS=ignore   # 警告しない

詳しくは 警告フィルタ と 警告フィルタの指定方法 を参照してください。

バージョン 3.15 で変更: message と module で正規表現が使えるようになりました。

PYTHONFAULTHANDLER

空でない文字列を設定すると、起動時に faulthandler.enable() を呼び出し、Python のトレースバックをダンプするハンドラを SIGSEGV、SIGFPE、SIGABRT、SIGBUS、SIGILL の各シグナルに設定します。 -X faulthandler オプションの指定と同じです。

Added in version 3.3.

PYTHONTRACEMALLOC

空でない文字列を設定すると、tracemalloc モジュールを使って Python のメモリ割り当ての追跡を開始します。 この変数の値は、追跡結果のトレースバックに保存するフレーム数の上限です。 例えば、PYTHONTRACEMALLOC=1 は最新のフレームだけを保存します。 詳細は tracemalloc.start() 関数を参照してください。 -X tracemalloc オプションの設定と同じです。

Added in version 3.4.

PYTHONPROFILEIMPORTTIME

1 を設定すると、Python は各インポートにかかる時間を表示します。 2 を設定すると、インポートしたモジュールがすでに読み込まれている場合の出力も含まれます。 -X importtime オプションの設定と同じです。

Added in version 3.7.

バージョン 3.14 で変更: 読み込み済みのモジュールのインポートも追跡する PYTHONPROFILEIMPORTTIME=2 を追加しました。

PYTHONASYNCIODEBUG

この環境変数が空でない文字列に設定された場合、asyncio モジュールの デバッグモード が有効化されます。

Added in version 3.4.

PYTHONMALLOC

Python のメモリアロケータの設定や、デバッグフックのインストールを行います。

Python が使うメモリアロケータの種類を設定します:

• default: デフォルトのメモリアロケータ を使います。

• malloc: すべてのドメイン (PYMEM_DOMAIN_RAW、PYMEM_DOMAIN_MEM、PYMEM_DOMAIN_OBJ) に C ライブラリの malloc() 関数を使います。

• pymalloc: PYMEM_DOMAIN_MEM および PYMEM_DOMAIN_OBJ ドメインには pymalloc アロケータ を使い、PYMEM_DOMAIN_RAW ドメインには malloc() 関数を使います。

• mimalloc: PYMEM_DOMAIN_MEM および PYMEM_DOMAIN_OBJ ドメインには mimalloc アロケータ を使い、PYMEM_DOMAIN_RAW ドメインには malloc() 関数を使います。

デバッグフック をインストールします:

• debug: デフォルトのメモリアロケータ にデバッグフックを追加します。

• malloc_debug: malloc と同じですが、デバッグフックもインストールします。

• pymalloc_debug: pymalloc と同じですが、デバッグフックもインストールします。

• mimalloc_debug: mimalloc と同じですが、デバッグフックもインストールします。

注釈

フリースレッド ビルドでは、malloc、malloc_debug、pymalloc、pymalloc_debug の値はサポートされていません。 default、debug、mimalloc、mimalloc_debug のみを受け付けます。

Added in version 3.6.

バージョン 3.7 で変更: "default" アロケータを追加しました。

PYTHONMALLOCSTATS

空でない文字列を設定すると、Python は新しいオブジェクトアリーナを作成するたびに、また終了時に、使用中の pymalloc メモリアロケータ または mimalloc メモリアロケータ の統計情報を表示します。

PYTHONMALLOC 環境変数を使って C ライブラリの malloc() アロケータを強制的に使用している場合、または pymalloc と mimalloc の両方のサポートを無効にして Python が構成されている場合は、この変数は無視されます。

バージョン 3.6 で変更: リリースモードでコンパイルされた Python でも、この変数を使用できるようになりました。 空文字列に設定した場合は、効果がなくなりました。

PYTHON_PYMALLOC_HUGEPAGES

ゼロ以外の整数を設定すると、pymalloc アリーナのヒュージページのサポートを有効にします。 無効にするには、0 に設定するか、未設定にします。 この変数を有効にするには、--with-pymalloc-hugepages を指定して Python をコンパイルする必要があります。

有効にすると、アリーナの割り当てに MAP_HUGETLB (Linux) または MEM_LARGE_PAGES (Windows) を使います。 ヒュージページが利用できない場合は、自動的に通常のページに切り替えます。

警告

Linux では、ヒュージページのプールが枯渇すると、os.fork() によって起きるコピーオンライトのフォールトを含むページフォールトにより、SIGBUS が送出されてプロセスが終了します。 ヒュージページのプールのサイズが適切で、fork の安全性が問題にならない環境でのみ有効にしてください。

Windows では、特別な権限が必要です。 詳細は Windows のラージページのドキュメント を参照してください。 必要な権限である SeLockMemoryPrivilege をユーザーが持っていない場合、Python は起動に失敗します。

Added in version 3.15.

PYTHONLEGACYWINDOWSFSENCODING

空でない文字列を設定すると、デフォルトの ファイルシステムのエンコーディングとエラーハンドラ のモードが、3.6 より前の値である、それぞれ 'mbcs' と 'replace' に戻ります。 それ以外の場合は、新しいデフォルト値の 'utf-8' と 'surrogatepass' が使われます。

sys._enablelegacywindowsfsencoding() を使うと、実行時に有効にすることもできます。

利用可能な環境: Windows.

Added in version 3.6: より詳しくは PEP 529 を参照してください。

PYTHONLEGACYWINDOWSSTDIO

空でない文字列を設定すると、新しいコンソールの読み書き処理を使わなくなります。 つまり、Unicode 文字は utf-8 ではなく、有効なコンソールコードページに従ってエンコードされます。

標準ストリームがコンソールバッファを参照せず、ファイルやパイプにリダイレクトされている場合は、この変数は無視されます。

利用可能な環境: Windows.

Added in version 3.6.

PYTHONCOERCECLOCALE

値を 0 に設定すると、Python のメインのコマンドラインアプリケーションは、従来の ASCII ベースの C および POSIX ロケールを、より機能の豊富な UTF-8 ベースのロケールに強制変換しなくなります。

この変数が 未設定 (または 0 以外の値に設定されている) で、ロケールを上書きする LC_ALL 環境変数も未設定であり、LC_CTYPE カテゴリの現在のロケールがデフォルトの C ロケールまたは明示的に ASCII ベースとされた POSIX ロケールの場合、Python CLI はインタープリタのランタイムを読み込む前に、次のロケールを記載順に LC_CTYPE カテゴリに設定しようとします:

• C.UTF-8

• C.utf8

• UTF-8

これらのロケールカテゴリのいずれかの設定に成功すると、Python ランタイムの初期化前に、現在のプロセスの環境内の LC_CTYPE 環境変数にも同じ設定を適用します。 これにより、更新された設定は、インタープリタ自体と、同じプロセス内で動作するロケールに対応したほかの構成要素 (GNU の readline ライブラリなど) の両方に加えて、サブプロセスにも伝わります (そのプロセスが Python インタープリタを実行しているかどうかは問いません)。 また、現在の C ロケールではなく環境を照会する操作 (Python 自体の locale.getdefaultlocale() など) にも伝わります。

これらのロケールのいずれかを、明示的に、または上記の暗黙的なロケールの強制変換によって設定すると、sys.stdin と sys.stdout に対して surrogateescape エラーハンドラ が自動的に有効になります (sys.stderr は、ほかのロケールと同じく backslashreplace を使い続けます)。 このストリームの処理方法は、通常と同様に PYTHONIOENCODING で上書きできます。

デバッグのために PYTHONCOERCECLOCALE=warn を設定すると、ロケールの強制変換が行われた場合、または強制変換の対象 となるはずの ロケールが Python ランタイムの初期化時にまだ有効だった場合に、Python は stderr に警告メッセージを出力します。

ロケールの強制変換を無効にした場合や、適切な変換先のロケールが見つからなかった場合でも、従来の ASCII ベースのロケールでは PYTHONUTF8 がデフォルトで有効になる点にも注意してください。 システムインターフェースでインタープリタに UTF-8 の代わりに ASCII を使わせるには、両方の機能を無効にする必要があります。

利用可能な環境: Unix.

Added in version 3.7: より詳しくは PEP 538 を参照をしてください。

PYTHONDEVMODE

空でない文字列を設定すると、Python 開発モード が有効になり、負荷が大きいためデフォルトでは有効にできない追加の実行時チェックを行います。 -X dev オプションの設定と同じです。

Added in version 3.7.

PYTHONUTF8

1 を設定すると、Python UTF-8 モード を有効にします。

0 を設定すると、Python UTF-8 モード を無効にします。

それ以外の空でない文字列を設定すると、インタープリタの初期化中にエラーが発生します。

Added in version 3.7.

PYTHONWARNDEFAULTENCODING

空でない文字列を設定すると、ロケール固有のデフォルトのエンコーディングを使用した場合に EncodingWarning が発生します。

詳細は EncodingWarning の有効化 を参照してください。

Added in version 3.10.

PYTHONNODEBUGRANGES

設定すると、コードオブジェクトの各命令に追加の位置情報 (終了行、開始列のオフセット、終了列のオフセット) を対応付けるテーブルを含めないようにします。 これは、コードオブジェクトや pyc ファイルを小さくしたい場合や、インタープリタがトレースバックを表示する際に追加の位置を示す表示を抑制したい場合に役立ちます。

Added in version 3.11.

PYTHONPERFSUPPORT

ゼロ以外の値を設定すると、Linux の perf プロファイラのサポートが有効になり、Python の呼び出しを検出できるようになります。

0 を設定すると、Linux の perf プロファイラのサポートを無効にします。

-X perf コマンドラインオプションと perf map 対応プロファイラのための Python のサポート も参照してください。

Added in version 3.12.

PYTHON_PERF_JIT_SUPPORT

ゼロ以外の値を設定すると、Linux の perf プロファイラのサポートが有効になり、DWARF 情報を使って Python の呼び出しを検出できるようになります。

0 を設定すると、Linux の perf プロファイラのサポートを無効にします。

-X perf_jit コマンドラインオプションと perf map 対応プロファイラのための Python のサポート も参照してください。

Added in version 3.13.

PYTHON_DISABLE_REMOTE_DEBUG

空でない文字列を設定すると、PEP 768 で説明されているリモートデバッグ機能を無効にします。 これには、別のプロセスでのコード実行を予約する機能と、現在のプロセスで実行するコードを受け取る機能の両方が含まれます。

-X disable-remote-debug コマンドラインオプションも参照してください。

Added in version 3.14.

PYTHON_CPU_COUNT

正の整数を設定すると、os.cpu_count() と os.process_cpu_count() の戻り値を上書きします。

-X cpu_count コマンドラインオプションも参照してください。

Added in version 3.13.

PYTHON_FROZEN_MODULES

If this variable is set to on or off, it determines whether or not frozen modules are ignored by the import machinery. A value of on means they get imported and off means they are ignored. The default is on for non-debug builds (the normal case) and off for debug builds. Note that the importlib_bootstrap and importlib_bootstrap_external frozen modules are always used, even if this flag is set to off.

-X frozen_modules コマンドラインオプションも参照してください。

Added in version 3.13.

PYTHON_COLORS

1 を設定すると、インタープリタはさまざまな出力に色を付けます。 0 を設定すると、この動作を無効にします。 色の制御 も参照してください。

Added in version 3.13.

PYTHON_BASIC_REPL

何らかの値を設定すると、インタープリタは readline を必要とする Python で実装された REPL を読み込もうとせず、代わりに従来のパーサに基づく REPL を使用します。

Added in version 3.13.

PYTHON_BASIC_COMPLETER

何らかの値を設定すると、PyREPL は色を使うデフォルトのタブ補完の代わりに、rlcompleter を使ってタブ補完を実装します。

Added in version 3.15.

PYTHON_HISTORY

この環境変数を使うと、.python_history ファイルの場所を設定できます (デフォルトは、ユーザーのホームディレクトリ内の .python_history です)。

Added in version 3.13.

PYTHON_GIL

1 を設定すると、グローバルインタープリタロック (GIL) を強制的に有効にします。 0 を設定すると GIL を強制的に無効にします (--disable-gil ビルドオプションを指定して構成した Python が必要です)。

この変数よりも優先される -X gil コマンドラインオプションと、フリースレッドの CPython も参照してください。

Added in version 3.13.

PYTHON_THREAD_INHERIT_CONTEXT

1 を設定すると、Thread はデフォルトで、Thread.start() の呼び出し元のコンテキストのコピーを使ってスレッドを開始します。 それ以外の場合、新しいスレッドは空のコンテキストで開始します。 未設定の場合、この変数のデフォルト値は、フリースレッドビルドでは 1、それ以外では 0 です。 -X thread_inherit_context も参照してください。

Added in version 3.14.

PYTHON_CONTEXT_AWARE_WARNINGS

1 を設定すると、warnings.catch_warnings コンテキストマネージャは、警告フィルタの状態の保存に ContextVar を使います。 未設定の場合、この変数のデフォルト値は、フリースレッドビルドでは 1、それ以外では 0 です。 -X context_aware_warnings を参照してください。

Added in version 3.14.

PYTHON_PATHCONFIG_WARNINGS

真 (1) の場合、sys.path モジュール検索パスの初期化 の際に stderr に警告を出力できます。 偽 (0) の場合は、これらの警告を抑制します。 デフォルトでは真に設定されます。 -X pathconfig_warnings も参照してください。

Added in version 3.15.

PYTHON_JIT

実験的な実行時コンパイルを利用できるビルドでは、この変数によってインタープリタの起動時に JIT を強制的に無効 (0) または有効 (1) にできます。

Added in version 3.13.

PYTHON_TLBC

1 を設定すると、スレッドローカルなバイトコードを有効にします。 0 を設定すると、スレッドローカルなバイトコードと特殊化インタープリタを無効にします。 --disable-gil を指定して構成したビルドでのみ適用されます。

-X tlbc コマンドラインオプションも参照してください。

Added in version 3.14.

PYTHON_LAZY_IMPORTS

遅延インポートの挙動を制御します。 2 つの値を受け付けます。 all ではすべてのインポートをデフォルトで遅延させ、normal (デフォルト) ではソースコード内の lazy キーワードに従います。

-X lazy_imports コマンドラインオプションも参照してください。

Added in version 3.15.

1.2.1. デバッグモード変数

PYTHONDUMPREFS

設定された場合、 Python はインタプリタのシャットダウン後に残っているオブジェクトと参照カウントをダンプします。

--with-trace-refs ビルドオプションを指定して構成した Python が必要です。

PYTHONDUMPREFSFILE

設定すると、Python はインタープリタのシャットダウン後にも残っているオブジェクトと参照カウントを、この環境変数の値で指定したパスのファイルにダンプします。

--with-trace-refs ビルドオプションを指定して構成した Python が必要です。

Added in version 3.11.

PYTHON_PRESITE

モジュールを設定すると、インタープリタのライフサイクルの早い段階、つまり site モジュールの実行前、かつ __main__ モジュールの作成前に、そのモジュールをインポートします。 したがって、インポートされたモジュールは __main__ として扱われません。

これは、Python の初期化の早い段階でコードを実行するために使用できます。

サブモジュールをインポートするには、import 文と同様に、値として package.module を指定します。

この変数よりも優先される -X presite コマンドラインオプションも参照してください。

--with-pydebug ビルドオプションを指定して構成した Python が必要です。

バージョン 3.15 で変更: エントリーポイントの形式として module:func も受け付けるようになりました。

Added in version 3.13.