`sys` --- システム固有のパラメーターと関数¶

このモジュールは、インタープリタが使用または管理する変数と、インタープリタに密接に関わる関数を提供します。常に利用できます。特に明記されていない限り、すべての変数は読み出し専用です。

sys.abiflags¶: Python が標準的な configure でビルトされた POSIX システムにおいて、PEP 3149 に記述された ABI フラグを含みます。

Added in version 3.2.

バージョン 3.8 で変更: デフォルトのフラグは空文字列になりました。 (pymalloc のための m フラグが取り除かれました)

利用可能な環境: Unix.

sys.addaudithook(hook)¶

呼び出し可能な hook を現在の(サブ)インタープリタのアクティブな監査用フックのリストに加えます。

sys.audit() 関数で監査イベントが発生すると、追加された順に各フックを呼び出し、イベント名と引数のタプルを渡します。まず PySys_AddAuditHook() で追加したネイティブのフックを呼び出し、次に現在の (サブ) インタープリタで追加したフックを呼び出します。フックは、イベントを記録したり、例外を送出して操作を中止したり、プロセス全体を終了させたりできます。

監査フックの主な用途は、Python や Python で書かれたライブラリが行う内部的な動作など、ほかの方法では観測できない動作の情報を集めることです。「サンドボックス」の実装には適していません。特に、この関数で追加したフックは悪意のあるコードによって簡単に無効化または回避され得ます。セキュリティに関わるフックは、少なくともランタイムの初期化前に C API の PySys_AddAuditHook() を使って追加する必要があります。また、任意のメモリ変更を許すモジュール (ctypes など) は完全に取り除くか、厳密に監視する必要があります。

sys.addaudithook() の呼び出し自体も、引数のない sys.addaudithook という監査イベントを発生させます。既存のフックが RuntimeError の派生例外を送出すると、新しいフックは追加されず、その例外は抑制されます。そのため、既存のフックをすべて制御していない限り、呼び出し側は自分のフックが追加されたとは仮定できません。

CPython が発生させるイベントの一覧は監査イベントの表、当初の設計に関する議論は PEP 578 を参照してください。

Added in version 3.8.

バージョン 3.8.1 で変更: RuntimeError ではない Exception は抑制されなくなりました。

トレースが有効な場合 (settrace() を参照)、Python のフックがトレースされるのは、その呼び出し可能オブジェクトに真の値を持つ __cantrace__ メンバーがある場合だけです。それ以外の場合、トレース関数はそのフックをスキップします。

sys.argv¶

Pythonスクリプトに渡されたコマンドライン引数のリスト。 argv[0] はスクリプトの名前となりますが、フルパス名かどうかは、OSによって異なります。コマンドライン引数に -c を付けて Pythonを起動した場合、 argv[0] は文字列 '-c' となります。スクリプト名なしでPythonを起動した場合、 argv[0] は空文字列になります。

標準入力もしくはコマンドライン引数で指定されたファイルのリストに渡ってループするには、 fileinput モジュールを参照してください。

sys.orig_argv も参照してください。

注釈

Unix では、コマンドライン引数は OS からバイト列で渡されます。 Python はそれをファイルシステムエンコーディングと "surrogateescape" エラーハンドラを使ってデコードします。オリジナルのバイト列が必要なときには、 [os.fsencode(arg) for arg in sys.argv] で取得できます。

sys.audit(event, *args)¶

監査イベントを発生させ、有効な監査フックを呼び出します。 event はイベントを識別する文字列です。 args には、そのイベントの詳しい情報を持つ引数を任意に含められます。各イベントの引数の数と型は安定した公開 API とみなされ、リリース間で変更すべきではありません。

例えば、監査イベントの 1 つに os.chdir があります。このイベントは path という引数を 1 つ持ち、要求された新しい作業ディレクトリが入ります。

sys.audit() は既存の監査フックをイベント名と引数を渡して呼び出し、いずれかのフックで最初に発生した例外を再送出します。一般に、例外が送出された場合は処理せず、できるだけ速やかにプロセスを終了させるべきです。これによってフックの実装が、特定のイベントへの対応を決められます。イベントを記録するだけにすることも、例外を送出して操作を中止することもできます。

フックは sys.addaudithook() または PySys_AddAuditHook() 関数で追加します。

この関数に対応するネイティブ関数は PySys_Audit() です。可能ならネイティブ関数を使うことを推奨します。

CPython が発生させるイベントの一覧は監査イベントの表を参照してください。

Added in version 3.8.

sys.base_exec_prefix¶

exec_prefix と同等ですが、基になる Python のインストール先を参照します。

仮想環境で実行すると、exec_prefix は仮想環境のプレフィックスに上書きされます。一方、base_exec_prefix は変わらず、常に基になる Python のインストール先を指します。詳しくは仮想環境を参照してください。

Added in version 3.3.

sys.base_prefix¶

prefix と同等ですが、基になる Python のインストール先を参照します。

仮想環境で実行すると、prefix は仮想環境のプレフィックスに上書きされます。一方、base_prefix は変わらず、常に基になる Python のインストール先を指します。詳しくは仮想環境を参照してください。

Added in version 3.3.

sys.byteorder¶: プラットフォームのバイト順を示します。ビッグエンディアン (最上位バイトが先頭) のプラットフォームでは 'big', リトルエンディアン (最下位バイトが先頭) では 'little' となります。

sys.builtin_module_names¶

コンパイル時にPythonインタプリタに組み込まれた、全てのモジュール名を含む文字列のタプル(この情報は、他の手段では取得することができません。 modules.keys() は、インポートされたモジュールのみのリストを返します。)

sys.stdlib_module_names の一覧も参照してください。

sys.call_tracing(func, args)¶

トレースを有効にして func(*args) を呼び出します。トレースの状態は保存され、呼び出し後に復元されます。デバッガのチェックポイントから呼び出し、ほかのコードを再帰的にデバッグまたはプロファイルするためのものです。

無限再帰を避けるため、settrace() または setprofile() で設定したトレース関数を呼び出している間、トレースは一時停止します。 call_tracing() を使うと、明示的にトレース関数を再帰呼び出しできます。

sys.copyright¶: Python インタプリタの著作権を表示する文字列です。

sys._clear_type_cache()¶

内部の型キャッシュをクリアします。型キャッシュは属性とメソッドの検索を高速化するために利用されます。この関数は、参照リークをデバッグするときに不要な参照を削除するためだけに利用してください。

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。

バージョン 3.13 で非推奨: 代わりに、より汎用的な _clear_internal_caches() 関数を使ってください。

sys._clear_internal_caches()¶: 性能向上のための内部キャッシュをすべてクリアします。この関数は、リークを調べるときに不要な参照やメモリブロックを解放するためだけに使ってください。

Added in version 3.13.

sys._current_frames()¶

各スレッドの識別子を関数が呼ばれた時点のそのスレッドでアクティブになっている一番上のスタックフレームに結びつける辞書を返します。モジュール traceback の関数を使えばそのように与えられたフレームのコールスタックを構築できます。

この関数はデッドロックをデバッグするのに非常に有効です。デッドロック状態のスレッドの協調動作を必要としませんし、そういったスレッドのコールスタックはデッドロックである限りフリーズしたままです。デッドロックにないスレッドのフレームについては、そのフレームを調べるコードを呼んだ時にはそのスレッドの現在の実行状況とは関係ないところを指し示しているかもしれません。

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。

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

sys._current_exceptions()¶

各スレッドの識別子を、関数の呼び出し時点でそのスレッドの最も内側で処理中の例外に対応付ける辞書を返します。例外を処理していないスレッドは、結果の辞書に含まれません。

統計的プロファイリングで特に便利です。

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。

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

バージョン 3.12 で変更: 辞書の各値が、sys.exc_info() が返すような 3 要素のタプルではなく、単一の例外インスタンスになりました。

sys.breakpointhook()¶

このフック関数は組み込みの breakpoint() から呼ばれます。デフォルトでは、この関数は pdb デバッガに処理を移行させますが、他の関数を設定することもでき、使用するデバッガを選べます。

この関数のシグネチャは何を呼び出すかに依存します。例えば、(pdb.set_trace() などの) デフォルトの結び付けでは引数は求められませんが、追加の引数 (位置引数およびキーワード引数) を求める関数に結び付けるかもしれません。組み込みの breakpoint() 関数は、自身の *args と **kws をそのまま渡します。 breakpointhooks() の返り値が何であれ、そのまま breakpoint() から返されます。

デフォルトの実装では、最初に環境変数 PYTHONBREAKPOINT を調べます。それが "0" に設定されていた場合は、この関数はすぐに終了します。つまり何もしません。この環境変数が設定されていないか、空文字列に設定されていた場合は、 pdb.set_trace() が呼ばれます。それ以外の場合は、この変数は実行する関数の名前である必要があります。関数名の指定では、例えば package.subpackage.module.function のようなドットでつながれた Python のインポートの命名体系を使ったを使います。この場合では、 package.subpackage.module がインポートされ、そのインポートされたモジュールには function() という呼び出し可能オブジェクトがなくてはなりません。この関数が渡された *args と **kws で実行され、 function() の返り値が何であれ sys.breakpointhook() は組み込みの breakpoint() 関数にその値をそのまま返します。

PYTHONBREAKPOINT で指名された呼び出し可能オブジェクトのインポートで何かしら問題が起きた場合、 RuntimeWarning が報告されブレークポイントは無視されることに注意してください。

また、 sys.breakpointhook() がプログラム上で上書きされていた場合は PYTHONBREAKPOINT は 調べられない ことにも注意してください。

Added in version 3.7.

sys._debugmallocstats()¶

CPython のメモリアロケータの状態に関する低レベルの情報を標準エラー出力に出力します。

Python がデバッグモードでビルドされている場合 (configure の --with-pydebug オプション)、コストの高い内部整合性の検査も行います。

Added in version 3.3.

この関数は CPython 固有です。正確な出力形式は定義されていませんし、変更されるかもしれません。

sys.dllhandle¶: Python DLLのハンドルを示す整数です。

利用可能な環境: Windows.

sys.displayhook(value)¶

value が None 以外の時、repr(value) を sys.stdout に出力し、value を builtins._ に保存します。 repr(value) がエラーハンドラを sys.stdout.errors (おそらく 'strict') として sys.stdout.encoding にエンコードできない場合、エラーハンドラを 'backslashreplace' として sys.stdout.encoding にエンコードします。

sys.displayhook は、Pythonの対話セッションで入力された式が評価されたときに呼び出されます。対話セッションの出力をカスタマイズする場合、 sys.displayhook に引数の数が一つの関数を指定します。

擬似コード:

def displayhook(value):
    if value is None:
        return
    # 再帰を避けるため '_' を None に設定する。
    builtins._ = None
    text = repr(value)
    try:
        sys.stdout.write(text)
    except UnicodeEncodeError:
        bytes = text.encode(sys.stdout.encoding, 'backslashreplace')
        if hasattr(sys.stdout, 'buffer'):
            sys.stdout.buffer.write(bytes)
        else:
            text = bytes.decode(sys.stdout.encoding, 'strict')
            sys.stdout.write(text)
    sys.stdout.write("\n")
    builtins._ = value

バージョン 3.2 で変更: UnicodeEncodeError が発生した場合は 'backslashreplace' エラーハンドラを使用するようになりました。

sys.dont_write_bytecode¶: この値が真の時、Python はソースモジュールをインポートする時に .pyc ファイルを生成しません。この値は -B コマンドラインオプションと PYTHONDONTWRITEBYTECODE 環境変数の値によって、起動時に True か False に設定されますが、実行時にこの変数を変更してバイトコード生成を制御することもできます。

sys._emscripten_info¶

wasm32-emscripten プラットフォームの環境に関する情報を持つ名前付きタプルです。この名前付きタプルは暫定的なもので、将来変更される可能性があります。

_emscripten_info.emscripten_version¶: Emscripten のバージョンを表す整数のタプル (major, minor, micro) です。例えば (3, 1, 8) です。

_emscripten_info.runtime¶: ランタイムを表す文字列です。例えばブラウザのユーザーエージェント、'Node.js v14.18.2'、'UNKNOWN' などです。

_emscripten_info.pthreads¶: Python が Emscripten の pthreads に対応するようコンパイルされていれば True です。

_emscripten_info.shared_memory¶: Python が共有メモリに対応するようコンパイルされていれば True です。

利用可能な環境: Emscripten.

Added in version 3.11.

sys.pycache_prefix¶

これを設定すると (None 以外にすると)、Python はソースコードツリー内の __pycache__ ディレクトリの代わりに、指定したディレクトリを根とする並行したディレクトリツリーで、バイトコードキャッシュの .pyc ファイルを読み書きします。ソースコードツリー内の __pycache__ ディレクトリはすべて無視され、新しい .pyc ファイルは指定した pycache プレフィックス内に書き込まれます。したがって、ビルドの前処理として compileall を使う場合は、実行時に使うものと同じ pycache プレフィックス (指定する場合) で実行する必要があります。

相対パスはカレント作業ディレクトリからの相対パスとして解釈されます。

この値は、-X pycache_prefix=PATH コマンドラインオプション、または環境変数 PYTHONPYCACHEPREFIX に基づいて初期設定されます (コマンドラインが優先されます)。どちらも設定されていなければ None です。

Added in version 3.8.

sys.excepthook(type, value, traceback)¶

指定したトレースバックと例外を sys.stderr に出力します。

SystemExit 以外の例外が送出されて捕捉されなかった場合、インタープリタは例外クラス、例外インスタンス、トレースバックオブジェクトの 3 つを引数として sys.excepthook を呼び出します。対話セッションではプロンプトに制御を戻す直前、Python プログラムではプログラムの終了直前に呼び出します。 sys.excepthook に引数を 3 つ取る別の関数を代入すると、このような最上位の例外の処理をカスタマイズできます。

捕捉されない例外が発生すると、引数 hook、type、value、traceback を持つ監査イベント sys.excepthook を発生させます。フックが設定されていなければ hook は None のことがあります。いずれかの監査フックが RuntimeError の派生例外を送出すると、例外フックの呼び出しを抑制します。それ以外の場合は、監査フックの例外を送出不能な例外として報告した後、sys.excepthook を呼び出します。

参考

送出不能な例外は sys.unraisablehook() 関数が処理し、threading.Thread.run() が送出した例外は threading.excepthook() 関数が処理します。

sys.__breakpointhook__¶
sys.__displayhook__¶
sys.__excepthook__¶
sys.__unraisablehook__¶: これらのオブジェクトはそれぞれ、プログラム起動時の breakpointhook, displayhook, excepthook, unraisablehook の値を保存しています。この値は、 breakpointhook, displayhook, excepthook, unraisablehook に不正なオブジェクトや別のオブジェクトが指定された場合に、元の値に復旧するために使用します。

Added in version 3.7: __breakpointhook__

Added in version 3.8: __unraisablehook__

sys.exception()¶

この関数を例外ハンドラ (except 節や except* 節など) の実行中に呼び出すと、そのハンドラが捕捉した例外インスタンスを返します。例外ハンドラが入れ子になっている場合、最も内側のハンドラが処理している例外だけを取得できます。

例外ハンドラが実行中でなければ、この関数は None を返します。

Added in version 3.11.

sys.exc_info()¶

処理中の例外を旧形式で返します。現在例外 e を処理している場合 (exception() が e を返す場合)、exc_info() はタプル (type(e), e, e.__traceback__) を返します。つまり、例外の型 (BaseException のサブクラス)、例外自体、および通常は例外が最後に発生した時点のコールスタックを保持するトレースバックオブジェクトを含むタプルです。

スタック内のどこでも例外を処理していなければ、None を 3 つ含むタプルを返します。

バージョン 3.11 で変更: type と traceback のフィールドは value (例外インスタンス) から得られるようになりました。そのため、処理中に例外を変更すると、その後の exc_info() の呼び出し結果に変更が反映されます。

sys.exec_prefix¶: Python のプラットフォーム依存なファイルがインストールされているディレクトリ名を示す文字列です。この値はサイト固有であり、デフォルトは '/usr/local' ですが、ビルド時に configure の --exec-prefix 引数で指定することができます。すべての設定ファイル (pyconfig.h など) は exec_prefix/lib/pythonX.Y/config に、共有ライブラリは exec_prefix/lib/pythonX.Y/lib-dynload にインストールされます (X.Y は 3.2 のような Python のバージョン番号)。

注釈

仮想環境が有効な場合、exec_prefix はその仮想環境を指します。基になる Python のインストール先の値は、引き続き base_exec_prefix で取得できます。詳しくは仮想環境を参照してください。

バージョン 3.14 で変更: 仮想環境での実行時に、prefix と exec_prefix が site ではなくパスの初期化によって仮想環境のプレフィックスに設定されるようになりました。そのため、site が無効でも (-S)、prefix と exec_prefix は常に仮想環境を指します。

sys.executable¶: Python インタプリタの実行ファイルの絶対パスを示す文字列です。このような名前が意味を持つシステムで利用可能です。Python が自身の実行ファイルの実際のパスを取得できない場合、sys.executable は空の文字列または None になります。

sys.exit([arg])¶

SystemExit 例外を送出し、インタープリタを終了する意図を示します。

省略可能な引数 arg には、終了ステータスを表す整数 (デフォルトはゼロ) または別の型のオブジェクトを指定できます。整数の場合、シェルなどはゼロを「正常終了」、ゼロ以外を「異常終了」とみなします。多くのシステムでは 0 から 127 の範囲である必要があり、それ以外の結果は未定義です。特定の終了コードに意味を割り当てる慣習を持つシステムもありますが、一般には十分に整備されていません。 Unix のプログラムでは、通常コマンドラインの構文エラーに 2、それ以外のすべてのエラーに 1 を使います。別の型のオブジェクトを渡した場合、None はゼロを渡すのと同じです。それ以外のオブジェクトは stderr に出力され、終了コードは 1 になります。特に sys.exit("some error message") は、エラー発生時に手早くプログラムを終了する方法です。

Since exit() ultimately "only" raises an exception, it will only exit the process when called from the main thread, and the exception is not intercepted. Cleanup actions specified by finally clauses of try statements are honored, and it is possible to intercept the exit attempt at an outer level.

バージョン 3.6 で変更: Python インタープリタが SystemExit を捕捉した後の後始末でエラーが起きた場合、終了ステータスは 120 に変更されます。標準ストリームのバッファにあるデータを書き出す際のエラーなどが該当します。

sys.flags¶

名前付きタプル flags はコマンドラインフラグの状態を公開します。各フラグにはインデックスではなく、名前でアクセスしてください。属性は読み出し専用です。

flags.debug¶	`-d`
flags.inspect¶	`-i`
flags.interactive¶	`-i`
flags.isolated¶	`-I`
flags.optimize¶	`-O` または `-OO`
flags.dont_write_bytecode¶	`-B`
flags.no_user_site¶	`-s`
flags.no_site¶	`-S`
flags.ignore_environment¶	`-E`
flags.verbose¶	`-v`
flags.bytes_warning¶	`-b`
flags.quiet¶	`-q`
flags.hash_randomization¶	`-R`
flags.dev_mode¶	`-X dev` (Python 開発モード)
flags.utf8_mode¶	`-X utf8`
flags.safe_path¶	`-P`
flags.int_max_str_digits¶	`-X int_max_str_digits` (整数文字列変換の長さ制限)
flags.warn_default_encoding¶	`-X warn_default_encoding`
flags.gil¶	`-X gil` と `PYTHON_GIL`
flags.thread_inherit_context¶	`-X thread_inherit_context` と `PYTHON_THREAD_INHERIT_CONTEXT`
flags.context_aware_warnings¶	`-X context_aware_warnings` と `PYTHON_CONTEXT_AWARE_WARNINGS`

バージョン 3.2 で変更: 新しい -q 向けに quiet 属性が追加されました。

Added in version 3.2.3: hash_randomization 属性が追加されました。

バージョン 3.3 で変更: 廃止済みの division_warning 属性を削除しました。

バージョン 3.4 で変更: -I isolated フラグ向けに isolated 属性が追加されました。

バージョン 3.7 で変更: 新しい Python 開発モード向けに dev_mode 属性が、新しい -X utf8 フラグ向けに utf8_mode 属性が追加されました。

バージョン 3.10 で変更: -X warn_default_encoding フラグに対応する warn_default_encoding 属性が追加されました。

バージョン 3.11 で変更: -P オプションに対応する safe_path 属性が追加されました。

バージョン 3.11 で変更: int_max_str_digits 属性が追加されました。

バージョン 3.13 で変更: gil 属性が追加されました。

バージョン 3.14 で変更: thread_inherit_context 属性が追加されました。

バージョン 3.14 で変更: context_aware_warnings 属性が追加されました。

sys.float_info¶

float 型に関する情報を保持している名前付きタプルです。精度と内部表現に関する低レベル情報を含んでいます。これらの値は 'C' 言語の標準ヘッダファイル float.h で定義されている様々な浮動小数点定数に対応しています。詳細は 1999 ISO/IEC C standard [C99] の 5.2.4.2.2 節 'Characteristics of floating types' を参照してください。

名前付きタプル `float_info` の属性¶
属性	float.h のマクロ	説明
float_info.epsilon¶	`DBL_EPSILON`	1.0 と、それより大きい float で表現可能な最小の値との差。 `math.ulp()` を参照してください。
float_info.dig¶	`DBL_DIG`	float で忠実に表現できる 10 進の最大桁数。下の説明を参照してください。
float_info.mant_dig¶	`DBL_MANT_DIG`	float の精度。基数を `radix` としたときの仮数部の桁数です。
float_info.max¶	`DBL_MAX`	float で表現可能な正の有限値の最大値。
float_info.max_exp¶	`DBL_MAX_EXP`	`radix**(e-1)` が float で表現可能な有限値となる最大の整数 e。
float_info.max_10_exp¶	`DBL_MAX_10_EXP`	`10**e` が float で表現可能な有限値の範囲内となる最大の整数 e。
float_info.min¶	`DBL_MIN`	float で表現可能な正の正規化数の最小値。 float で表現可能な正の非正規化数の最小値を得るには `math.ulp(0.0)` を使ってください。
float_info.min_exp¶	`DBL_MIN_EXP`	`radix**(e-1)` が正規化された float となる最小の整数 e。
float_info.min_10_exp¶	`DBL_MIN_10_EXP`	`10**e` が正規化された float となる最小の整数 e。
float_info.radix¶	`FLT_RADIX`	指数表現の基数。
float_info.rounds¶	`FLT_ROUNDS`	浮動小数点演算の丸めモードを表す整数です。インタープリタ起動時のシステムの `FLT_ROUNDS` マクロの値を反映します: `-1`: 不定 `0`: ゼロ方向 `1`: 最近接値 `2`: 正の無限大方向 `3`: 負の無限大方向 `FLT_ROUNDS` のそれ以外の値は、実装が定義する丸め動作を表します。

The attribute sys.float_info.dig needs further explanation. If s is any string representing a decimal number with at most sys.float_info.dig significant digits, then converting s to a float and back again will recover a string representing the same decimal value:

>>> import sys
>>> sys.float_info.dig
15
>>> s = '3.14159265358979'    # 有効桁数 15 桁の 10 進文字列
>>> format(float(s), '.15g')  # float に変換してから戻すと同じ値になる。
'3.14159265358979'

ただし、文字列が有効桁数 sys.float_info.dig より大きい場合には、常に復元されるとは限りません:

>>> s = '9876543211234567'    # 有効桁数 16 桁は多すぎる!
>>> format(float(s), '.16g')  # 変換で値が変わる。
'9876543211234568'

sys.float_repr_style¶: repr() 関数が浮動小数点数に対してどう振る舞うかを示す文字列です。この文字列が値 'short' を持てば、有限の浮動小数点数 x に対して、repr(x) は float(repr(x)) == x を満たす短い文字列を返そうとします。これは、Python 3.1 以降での標準の振る舞いです。それ以外の場合、float_repr_style は値 'legacy' を持ち、repr(x) は 3.1 以前のバージョンの Python と同じように振る舞います。

Added in version 3.1.

sys.getallocatedblocks()¶

インタープリタが現在割り当てているメモリブロックの数を、サイズによらず返します。主にメモリリークの追跡やデバッグに役立ちます。インタープリタの内部キャッシュにより結果は呼び出しごとに変わり得るため、より予測しやすい結果を得るには _clear_internal_caches() と gc.collect() を呼び出す必要があることがあります。

Python のビルドや実装によって、この情報を妥当な方法で計算できない場合、getallocatedblocks() は代わりに 0 を返しても構いません。

Added in version 3.4.

sys.getunicodeinternedsize()¶: インターンされた Unicode オブジェクトの数を返します。

Added in version 3.12.

sys.getandroidapilevel()¶: ビルド時の Android API レベルを整数として返します。この Python ビルドを実行できる Android の最小バージョンを表します。実行時のバージョン情報については platform.android_ver() を参照してください。

利用可能な環境: Android.

Added in version 3.7.

sys.getdefaultencoding()¶: 'utf-8' を返します。 str.encode() などのメソッドで使うデフォルトの文字列エンコーディングの名前です。

sys.getdlopenflags()¶: dlopen() 呼び出しに使うフラグの現在の値を返します。フラグの値を表すシンボル名は os モジュールにあります (os.RTLD_LAZY などの RTLD_xxx 定数)。

利用可能な環境: Unix.

sys.getfilesystemencoding()¶

ファイルシステムエンコーディングを取得します。これは、Unicode のファイル名とバイト列のファイル名を相互に変換するために、ファイルシステムエラーハンドラとともに使うエンコーディングです。ファイルシステムエラーハンドラは getfilesystemencodeerrors() が返します。

最良の互換性のために、たとえファイル名の表現に bytes がサポートされていたとしても、全てのケースで str をファイル名に使うべきです。ファイル名を受け取ったり返したりする関数は str と bytes をサポートし、すぐにシステムにとって好ましい表現に変換すべきです。

os.fsencode() や os.fsdecode() を、正しいエンコーディングやエラーモードが使われていることを保証するために使うべきです。

ファイルシステムのエンコーディングとエラーハンドラは、Python の開始時に PyConfig_Read() 関数により設定されます。 PyConfig のメンバー filesystem_encoding と filesystem_errors を参照してください。

バージョン 3.2 で変更: getfilesystemencoding() の結果が None になることはなくなりました。

バージョン 3.6 で変更: Windows はもう 'mbcs' を返す保証は無くなりました。より詳しいことは PEP 529 および _enablelegacywindowsfsencoding() を参照してください。

バージョン 3.7 で変更: Python UTF-8 モードが有効なら "utf-8" を返します。

sys.getfilesystemencodeerrors()¶

ファイルシステムエラーハンドラを取得します。これは、Unicode のファイル名とバイト列のファイル名を相互に変換するために、ファイルシステムエンコーディングとともに使うエラーハンドラです。ファイルシステムエンコーディングは getfilesystemencoding() が返します。

os.fsencode() や os.fsdecode() を、正しいエンコーディングやエラーモードが使われていることを保証するために使うべきです。

ファイルシステムのエンコーディングとエラーハンドラは、Python の開始時に PyConfig_Read() 関数により設定されます。 PyConfig のメンバー filesystem_encoding と filesystem_errors を参照してください。

Added in version 3.6.

sys.get_int_max_str_digits()¶: 整数文字列変換の長さ制限の現在の値を返します。 set_int_max_str_digits() も参照してください。

Added in version 3.11.

sys.getrefcount(object)¶

object の参照数を返します。 object は (一時的に) getrefcount() からも参照されるため、参照数は予想される数よりも 1 多くなります。

戻り値は、実際に保持されているオブジェクトの参照の数を実際に反映しているとは限らないことに注意してください。例えば、一部のオブジェクトは永続 (immortal) であり、実際の参照の数を反映しない非常に高い参照数を持ちます。したがって、 0 か 1 の値以外では、正確な戻り値に頼らないでください。

参照カウントが大きい永続オブジェクトは、_is_immortal() で識別できます。

バージョン 3.12 で変更: 永続オブジェクトの参照カウントは非常に大きく、実際の参照数とは一致しません。

sys.getrecursionlimit()¶: 現在の最大再帰数を返します。最大再帰数は、Python インタプリタスタックの最大の深さです。この制限は Python プログラムが無限に再帰し、C スタックがオーバーフローしてクラッシュすることを防止するために設けられています。この値は setrecursionlimit() で指定することができます。

sys.getsizeof(object[, default])¶

object のサイズをバイト数で返します。object は任意の型のオブジェクトです。すべての組み込みオブジェクトは正しい値を返します。サードパーティー製の型については実装依存になります。

オブジェクトに直接起因するメモリ消費のみを表し、参照するオブジェクトは含みません。

オブジェクトがサイズを取得する手段を提供していない時は default が返されます。default が指定されていない場合は TypeError が送出されます。

getsizeof() はオブジェクトの __sizeof__ メソッドを呼び出します。オブジェクトがガベージコレクタに管理されている場合は、ガベージコレクタの管理に必要な追加のメモリ量を結果に加算します。

コンテナとその内容すべてのサイズを調べるために getsizeof() を再帰的に使う例は、recursive sizeof recipe を参照してください。

sys.getswitchinterval()¶: インタープリタの「スレッド切り替え間隔」を秒単位で返します。 setswitchinterval() を参照してください。

Added in version 3.2.

sys._getframe([depth])¶

コールスタックからフレームオブジェクトを返します。オプション引数 depth を指定すると、スタックのトップから depth だけ下のフレームオブジェクトを取得します。 depth がコールスタックよりも深ければ、 ValueError が発生します。 depth のデフォルト値は 0 で、この場合はコールスタックのトップのフレームを返します。

引数 frame で監査イベント sys._getframe を送出します。

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。全ての Python 実装で存在することが保証されているわけではありません。

sys._getframemodulename([depth])¶

コールスタックからモジュール名を返します。省略可能な整数 depth を指定すると、スタックの先頭からその回数だけ呼び出しをさかのぼった位置のモジュールを返します。コールスタックより深い位置を指定した場合や、モジュールを識別できない場合は None を返します。 depth のデフォルトはゼロで、コールスタックの先頭のモジュールを返します。

引数 depth を持つ監査イベント sys._getframemodulename を発生させます。

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。全ての Python 実装で存在することが保証されているわけではありません。

Added in version 3.12.

sys.getobjects(limit[, type])¶

この関数は、特殊な configure オプション --with-trace-refs を使って CPython をビルドした場合にだけ存在します。ガベージコレクションの問題をデバッグするためだけのものです。

動的に割り当てられた Python オブジェクトを最大 limit 個含むリストを返します。 type を指定した場合、その型に正確に一致するオブジェクトだけを含めます (サブタイプは含みません)。

このリスト内のオブジェクトを使うのは安全ではありません。特に、結果にはオブジェクトアロケータの状態を共有するすべてのインタープリタのオブジェクトが含まれます。具体的には、PyInterpreterConfig.use_main_obmalloc を 1 にして作成したインタープリタ、Py_NewInterpreter() で作成したインタープリタ、およびメインインタープリタです。異なるインタープリタのオブジェクトを混在させると、クラッシュや予期しない動作につながることがあります。

この関数は特殊な目的にだけ使ってください。すべての Python 実装に存在する保証はありません。

バージョン 3.14 で変更: 結果に、ほかのインタープリタのオブジェクトが含まれることがあります。

sys.getprofile()¶: setprofile() 関数で設定したプロファイラ関数を取得します。

sys.gettrace()¶: settrace() 関数で設定したトレース関数を取得します。

gettrace() 関数は、デバッガ、プロファイラ、カバレッジツールなどの実装に使うことのみを想定しています。この関数の振る舞いは言語定義ではなく実装プラットフォームの一部です。そのため、他の Python 実装では利用できないかもしれません。

sys.getwindowsversion()¶

実行中の Windows バージョンを示す、名前付きタプルを返します。名前の付いている要素は、 major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type, platform_version です。 service_pack は文字列を含み、 platform_version は 3-タプル、それ以外は整数です。この構成要素には名前でもアクセスできるので、 sys.getwindowsversion()[0] は sys.getwindowsversion().major と等価です。先行のバージョンとの互換性のため、最初の 5 要素のみが添字の指定で取得できます。

platform は 2 (VER_PLATFORM_WIN32_NT) です。

product_type は、以下の値のいずれかになります。:

定数	意味
`1` (VER_NT_WORKSTATION)	システムはワークステーションです。
`2` (VER_NT_DOMAIN_CONTROLLER)	システムはドメインコントローラです。
`3` (VER_NT_SERVER)	システムはサーバですが、ドメインコントローラではありません。

この関数は Win32 の GetVersionEx() 関数をラップします。各フィールドについて詳しくは、Microsoft の OSVERSIONINFOEX() のドキュメントを参照してください。

platform_version は、プロセスでエミュレートされているバージョンではなく、現在のオペレーティングシステムのメジャーバージョン、マイナーバージョン、ビルドナンバーを返します。この関数は機能の検知ではなくロギングで使うためのものです。

注釈

platform_version は kernel32.dll からバージョンを取得しますが、そのバージョンは OS のバージョンと異なることがあります。正確な OS のバージョンを得るには platform モジュールを使ってください。

利用可能な環境: Windows.

バージョン 3.2 で変更: 名前付きタプルに変更され、 service_pack_minor, service_pack_major, suite_mask, および product_type が追加されました。

バージョン 3.6 で変更: platform_version の追加

sys.get_asyncgen_hooks()¶: asyncgen_hooks オブジェクトを返します。これは (firstiter, finalizer) という形の namedtuple に似たオブジェクトです。 firstiter と finalizer は、それぞれ None または非同期ジェネレータイテレータを引数に取る関数であることを想定しています。これらは、イベントループが非同期ジェネレータの終了処理をスケジュールするために使います。

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

注釈

この関数は暫定的に追加されました (詳しくは PEP 411 を参照)。

sys.get_coroutine_origin_tracking_depth()¶: set_coroutine_origin_tracking_depth() で設定した、現在のコルーチン生成元の追跡の深さを取得します。

Added in version 3.7.

注釈

この関数は暫定的に追加されました (詳しくは PEP 411 を参照)。デバッグ目的でのみ使ってください。

sys.hash_info¶

数値のハッシュ実装のパラメータを与える named tuple です。数値型のハッシュ化についての詳細は数値型のハッシュ化を参照してください。

hash_info.width¶: ハッシュ値に使うビット幅。

hash_info.modulus¶: 数値のハッシュ計算で剰余の法として使う素数 P。

hash_info.inf¶: 正の無限大に対して返すハッシュ値。

hash_info.nan¶: (この属性は現在使われていません)

hash_info.imag¶: 複素数の虚部に使う乗数。

hash_info.algorithm¶: str、bytes、memoryview のハッシュに使うアルゴリズムの名前。

hash_info.hash_bits¶: ハッシュアルゴリズムの内部の出力サイズ。

hash_info.seed_bits¶: ハッシュアルゴリズムのシードキーのサイズ。

hash_info.cutoff¶: 短い文字列に対する DJBX33A の最適化を適用する範囲 [1, cutoff) の上限。

Added in version 3.2.

バージョン 3.4 で変更: algorithm、hash_bits、seed_bits、cutoff が追加されました。

sys.hexversion¶

一つの整数にエンコードされたバージョン番号。この値は新バージョン(正規リリース以外であっても)ごとにかならず増加します。例えば、Python 1.5.2 以降でのみ動作するプログラムでは、以下のようなチェックを行います。

if sys.hexversion >= 0x010502F0:
    # 新しい機能を使う。
    ...
else:
    # 代替実装を使うか、利用者に警告する。
    ...

組み込み関数 hex() に渡した結果として表示すると意味が分かるため、hexversion と呼ばれています。同じ情報をより人間に読みやすい形式で取得するには、named tuple の sys.version_info を使用できます。

hexversion のより詳しい情報については API と ABI のバージョニングを参照してください。

sys.implementation¶

現在起動している Python インタプリタに関する情報が格納されたオブジェクトです。すべての Python 実装において、以下の属性が存在することが要求されています。

name は実装の識別子です (例: 'cpython')。実際の文字列は Python 実装によって定義されますが、小文字であることが保証されています。

version は sys.version_info と同じ形式の、Python 実装のバージョンを表す名前付きタプルです。これは現在起動しているインタプリタ固有のバージョンを意味します。sys.version_info は Python 言語のバージョンであり、これはそのバージョンに準拠した実装のバージョンです。例えば、PyPy 1.8 の sys.implementation.version は sys.version_info(1, 8, 0, 'final', 0) になるのに対し、 sys.version_info は sys.version_info(2, 7, 2, 'final', 0) になります。CPython は、それがリファレンス実装であるため、両者は同じ値になります。

hexversion は sys.hexversion と同形式の、16 進数での実装のバージョンです。

cache_tag は、キャッシュされたモジュールのファイル名に使用されるタグです。慣例により、これは実装名とバージョンを組み合わせた文字列になります (例: 'cpython-33') が、Python 実装はその他の適切な値を使う場合があります。cache_tag に None が設定された場合、モジュールのキャッシングが無効になっていることを示します。

supports_isolated_interpreters は、この実装が複数の独立したインタープリタをサポートするかを示す真偽値です。 CPython ではほとんどのプラットフォームで True です。この機能に対応するプラットフォームは、低水準の _interpreters モジュールを実装します。

参考

PEP 684、PEP 734、concurrent.interpreters。

sys.implementation には Python 実装固有の属性を追加することができます。それら非標準属性の名前はアンダースコアから始めなくてはならず、そしてここでは説明されません。その内容に関係なく、sys.implementation はインタプリタ起動中や実装のバージョン間で変更することはありません (ただし Python 言語のバージョン間についてはその限りではありません)。詳細は PEP 421 を参照してください。

Added in version 3.3.

バージョン 3.14 で変更: supports_isolated_interpreters フィールドが追加されました。

注釈

必須の属性を新しく追加するには、通常の PEP の手続きを経る必要があります。詳しくは PEP 421 を参照してください。

sys.int_info¶

Python における整数の内部表現に関する情報を保持する、named tuple です。この属性は読み出し専用です。

int_info.bits_per_digit¶: 各桁に格納するビット数です。 Python の整数は内部的に 2**int_info.bits_per_digit を基数として格納されます。

int_info.sizeof_digit¶: 1 桁を表すために使う C の型のサイズ (バイト単位) です。

int_info.default_max_str_digits¶: 明示的に設定していない場合の sys.get_int_max_str_digits() のデフォルト値です。

int_info.str_digits_check_threshold¶: sys.set_int_max_str_digits()、PYTHONINTMAXSTRDIGITS、-X int_max_str_digits に指定できる、ゼロ以外の最小値です。

Added in version 3.1.

バージョン 3.11 で変更: default_max_str_digits と str_digits_check_threshold が追加されました。

sys.__interactivehook__¶

この属性が存在する場合、インタープリタが対話モードで起動したときに値は (引数なしで) 自動的に呼ばれます。これは PYTHONSTARTUP ファイルの読み込み後に行われるため、それにこのフックを設定することが出来ます。site モジュールで設定します。

起動時にフックを呼び出す際、フックオブジェクトを引数とする監査イベント cpython.run_interactivehook を発生させます。

Added in version 3.4.

sys.intern(string)¶

string を「インターンされた」文字列のテーブルに登録し、インターンされた文字列 (string 自体またはそのコピー) を返します。文字列のインターンは、辞書の検索性能を少し向上させるのに役立ちます。辞書のキーと検索に使うキーの両方がインターンされていれば、ハッシュ計算後のキーの比較を文字列の比較ではなくポインタの比較で行えるためです。通常、Python プログラムで使う名前は自動的にインターンされ、モジュール、クラス、インスタンスの属性を保持する辞書のキーもインターンされています。

Interned strings are not immortal; you must keep a reference to the return value of intern() around to benefit from it.

sys._is_gil_enabled()¶: GIL が有効なら True、無効なら False を返します。

Added in version 3.13.

すべての Python 実装に存在する保証はありません。

sys.is_finalizing()¶

メインの Python インタープリタが終了処理中なら True を返します。それ以外の場合は False を返します。

PythonFinalizationError 例外も参照してください。

Added in version 3.5.

sys._jit¶

実行時コンパイル (JIT コンパイル) の状態を調べるための機能です。

JIT コンパイルは CPython の 実験的な実装の詳細 です。 sys._jit は、すべての Python の実装、バージョン、ビルド構成に存在する保証も、同じ動作をする保証もありません。

Added in version 3.14.

_jit.is_available()¶: 現在の Python 実行ファイルが JIT コンパイルに対応していれば True、そうでなければ False を返します。 Windows では --experimental-jit、それ以外のすべてのプラットフォームでは --enable-experimental-jit オプションを使って CPython をビルドすることで制御できます。

_jit.is_enabled()¶: 現在の Python プロセスで JIT コンパイルが有効なら True、そうでなければ False を返します (有効なら sys._jit.is_available() も真です)。 JIT コンパイルを利用できる場合、インタープリタ起動時に環境変数 PYTHON_JIT を 0 (無効) または 1 (有効) に設定して制御できます。

_jit.is_active()¶

最上位の Python フレームが現在 JIT コードを実行していれば True、そうでなければ False を返します (実行していれば sys._jit.is_enabled() も真です)。

注釈

この関数は JIT 自体のテストとデバッグ用です。ほかの目的では使わないでください。

注釈

トレーシング JIT コンパイラの性質上、この関数を繰り返し呼び出すと予想外の結果になることがあります。例えば、戻り値によって分岐し、その分岐が JIT コードへの移行や JIT コードからの離脱を引き起こす場合は、予期しない動作につながりやすくなります:

>>> for warmup in range(BIG_NUMBER):
...     # この行は頻繁に実行され、やがて JIT コンパイルされる。
...     if sys._jit.is_active():
...         # この行はめったに実行されず、インタープリタで実行される。
...         assert sys._jit.is_active()
...
Traceback (most recent call last):
  File "<stdin>", line 5, in <module>
    assert sys._jit.is_active()
           ~~~~~~~~~~~~~~~~~~^^
AssertionError

sys.last_exc¶: この変数は常に定義されているわけではありません。例外が処理されず、インタープリタがエラーメッセージとスタックのトレースバックを表示したとき、その例外インスタンスが設定されます。対話的な利用者が、エラーを起こしたコマンドを再実行せずにデバッガモジュールをインポートして、事後デバッグを始められるようにするためのものです。典型的には import pdb; pdb.pm() で事後デバッガに入ります。詳しくは pdb モジュールを参照してください。

Added in version 3.12.

sys._is_immortal(op)¶: 指定したオブジェクトが永続なら True、そうでなければ False を返します。

注釈

永続オブジェクト (この関数に渡すと True を返すオブジェクト) が将来のバージョンでも永続である保証はありません。逆に、永続でないオブジェクトが将来も永続でない保証もありません。

Added in version 3.14.

この関数は特殊な目的にだけ使ってください。すべての Python 実装に存在する保証はありません。

sys._is_interned(string)¶: 指定した文字列が「インターンされている」なら True、そうでなければ False を返します。

Added in version 3.13.

すべての Python 実装に存在する保証はありません。

sys.last_type¶
sys.last_value¶
sys.last_traceback¶: これら 3 つの変数は非推奨です。代わりに sys.last_exc を使ってください。これらは、前述の exc_info() が返すような旧形式で sys.last_exc を保持します。

sys.maxsize¶: Py_ssize_t 型の変数が取りうる最大値を示す整数です。通常、32 ビットプラットフォームでは 2**31 - 1、64 ビットプラットフォームでは 2**63 - 1 になります。

sys.maxunicode¶: Unicode コードポイントの最大値を示す整数、すなわち 1114111 (16 進数で 0x10FFFF) です。

バージョン 3.3 で変更: PEP 393 以前は、オプション設定にUnicode文字の保存形式がUCS-2とUCS-4のどちらを指定したかによって、 sys.maxunicode の値は 0xFFFF が 0x10FFFF になっていました。

sys.meta_path¶

メタパスファインダオブジェクトのリストです。各オブジェクトの find_spec() メソッドを呼び出し、インポートするモジュールを見つけられるか調べます。デフォルトでは、Python の標準のインポート動作を実装する項目が入っています。 find_spec() には、少なくともインポート対象のモジュールの絶対名を渡します。モジュールがパッケージ内にある場合は、親パッケージの __path__ 属性を第 2 引数として渡します。このメソッドはモジュール仕様を返し、モジュールが見つからなければ None を返します。

参考

importlib.abc.MetaPathFinder: meta_path 上のファインダオブジェクトのインターフェースを定義する抽象基底クラスです。
importlib.machinery.ModuleSpec: find_spec() がインスタンスを返すべき具象クラスです。

バージョン 3.4 で変更: モジュール仕様は、PEP 451 によって Python 3.4 で導入されました。

バージョン 3.12 で変更: meta_path の項目に find_spec() メソッドがない場合に find_module() メソッドを探す代替処理を削除しました。

sys.modules¶: モジュール名を、ロード済みのモジュールに対応付ける辞書です。これを操作して、モジュールを強制的に再ロードするなどの処理ができます。ただし、辞書自体を置き換えても期待どおりに動くとは限らず、必須の項目を削除すると Python が動作しなくなることがあります。このグローバルな辞書を反復処理する場合は、常に sys.modules.copy() または tuple(sys.modules) を使ってください。コードの副作用や別のスレッドの動作によって反復処理中にサイズが変わり、例外が発生することを避けるためです。

sys.orig_argv¶

Python の実行ファイルに渡された、元のコマンドライン引数のリストです。

sys.orig_argv の要素は Python インタープリタへの引数で、sys.argv の要素は利用者のプログラムへの引数です。インタープリタ自体が消費する引数は sys.orig_argv に含まれ、sys.argv には含まれません。

Added in version 3.10.

sys.path¶

モジュールを検索するパスを示す文字列のリスト。 PYTHONPATH 環境変数と、インストール時に指定したデフォルトパスで初期化されます。

デフォルトでは、プログラム起動時の初期化で、安全でない可能性があるパスを sys.path の先頭に追加します (PYTHONPATH によって挿入する項目より前です):

コマンドラインが python -m module の場合: カレント作業ディレクトリを先頭に追加します。
コマンドラインが python script.py の場合: スクリプトのディレクトリを先頭に追加します。スクリプトがシンボリックリンクなら、リンクを解決します。
コマンドラインが python -c code または python (REPL) の場合: カレント作業ディレクトリを意味する空文字列を先頭に追加します。

安全でない可能性があるこのパスを先頭に追加しないようにするには、-P コマンドラインオプションまたは環境変数 PYTHONSAFEPATH を使ってください。

プログラムはその目的のために、このリストを自由に修正できます。文字列だけが sys.path に追加でき、ほかの全てのデータ型はインポート中に無視されます。

参考

site モジュールのドキュメントで、 .pth ファイルを使って sys.path を拡張する方法を解説しています。

sys.path_hooks¶

path を引数にとって、その path に対する finder の作成を試みる呼び出し可能オブジェクトのリスト。 finder の作成に成功したら、その呼出可能オブジェクトのは finder を返します。失敗した場合は、 ImportError を発生させます。

オリジナルの仕様は PEP 302 を参照してください。

sys.path_importer_cache¶

finder オブジェクトのキャッシュ機能を果たす辞書です。キーは sys.path_hooks に渡されているパスで、値は見つかった finder になります。パスが正常なファイルシステムパスであり、finder が sys.path_hooks 上に見つからない場合は None が格納されます。

オリジナルの仕様は PEP 302 を参照してください。

sys.platform¶

プラットフォーム識別子を含む文字列です。既知の値は次のとおりです:

システム	`platform` の値
AIX	`'aix'`
Android	`'android'`
Emscripten	`'emscripten'`
FreeBSD	`'freebsd'`
iOS	`'ios'`
Linux	`'linux'`
macOS	`'darwin'`
Windows	`'win32'`
Windows/Cygwin	`'cygwin'`
WASI	`'wasi'`

表にない Unix システムでは、Python のビルド時 に uname -s が返した OS 名を小文字にし、uname -r が返したバージョンの最初の部分を付けた値になります。例えば 'sunos5' です。そのため、特定のシステムバージョンを判別したいのでなければ、次の書き方を推奨します。

if sys.platform.startswith('sunos'):
    # ここに SunOS 固有のコードを書く。

バージョン 3.3 で変更: Linux では sys.platform がメジャーバージョンを含まなくなりました。 'linux2' や 'linux3' ではなく、常に 'linux' です。

バージョン 3.8 で変更: AIX では sys.platform がメジャーバージョンを含まなくなりました。 'aix5' や 'aix7' ではなく、常に 'aix' です。

バージョン 3.13 で変更: Android では sys.platform が 'linux' ではなく 'android' を返すようになりました。

バージョン 3.14 で変更: FreeBSD では sys.platform がメジャーバージョンを含まなくなりました。 'freebsd13' や 'freebsd14' ではなく、常に 'freebsd' です。

参考

os.name はより粗い分類を提供します。 os.uname() はシステムに依存したバージョン情報を提供します。

platform モジュールはシステムの詳細な識別情報をチェックする機能を提供しています。

sys.platlibdir¶

プラットフォーム固有のライブラリディレクトリの名前です。標準ライブラリや、インストール済みの拡張モジュールのパスを組み立てるために使います。

ほとんどのプラットフォームでは "lib" です。 Fedora と SuSE の 64 ビットプラットフォームでは "lib64" になり、sys.path には次のパスが入ります (X.Y は Python の major.minor バージョンです):

/usr/lib64/pythonX.Y/: 標準ライブラリ (os モジュールの os.py など)
/usr/lib64/pythonX.Y/lib-dynload/: 標準ライブラリの C 拡張モジュール (errno モジュールなど。正確なファイル名はプラットフォームに依存します)
/usr/lib/pythonX.Y/site-packages/ (sys.platlibdir ではなく、常に lib を使用): サードパーティーモジュール
/usr/lib64/pythonX.Y/site-packages/: サードパーティーパッケージの C 拡張モジュール

Added in version 3.9.

sys.prefix¶: プラットフォームに依存しない Python のファイルがインストールされている、サイト固有のディレクトリプレフィックスを表す文字列です。 Unix でのデフォルトは /usr/local です。ビルド時に configure スクリプトの --prefix 引数で設定できます。これを基にしたパスについてはインストールパスを参照してください。

注釈

仮想環境が有効な場合、prefix はその仮想環境を指します。基になる Python のインストール先の値は、引き続き base_prefix で取得できます。詳しくは仮想環境を参照してください。

バージョン 3.14 で変更: 仮想環境での実行時に、prefix と exec_prefix が site ではなくパスの初期化によって仮想環境のプレフィックスに設定されるようになりました。そのため、site が無効でも (-S)、prefix と exec_prefix は常に仮想環境を指します。

sys.ps1¶
sys.ps2¶: インタプリタの一次プロンプト、二次プロンプトを指定する文字列。対話モードで実行中のみ定義され、初期値は '>>> ' と '... ' です。文字列以外のオブジェクトを指定した場合、インタプリタが対話コマンドを読み込むごとにオブジェクトの str() を評価します。この機能は、動的に変化するプロンプトを実装する場合に利用します。

sys.setdlopenflags(n)¶: Set the flags used by the interpreter for dlopen() calls, such as when the interpreter loads extension modules. Among other things, this will enable a lazy resolving of symbols when importing a module, if called as sys.setdlopenflags(0). To share symbols across extension modules, call as sys.setdlopenflags(os.RTLD_GLOBAL). Symbolic names for the flag values can be found in the os module (RTLD_xxx constants, e.g. os.RTLD_LAZY).

利用可能な環境: Unix.

sys.set_int_max_str_digits(maxdigits)¶: このインタープリタが使う整数文字列変換の長さ制限を設定します。 get_int_max_str_digits() も参照してください。

Added in version 3.11.

sys.setprofile(profilefunc)¶

システムのプロファイル関数を設定します。 Python のソースコード用のプロファイラを Python で実装するために使えます。 Python プロファイラについて詳しくは The Python Profilers の章を参照してください。システムのプロファイル関数はトレース関数 (settrace() を参照) と同じように呼び出されますが、受け取るイベントが異なります。例えば、実行するコードの行ごとには呼び出されず、呼び出しと復帰のときだけ呼ばれます (ただし例外が発生していても復帰イベントは通知されます)。この関数はスレッド固有ですが、プロファイラはスレッド間のコンテキスト切り替えを知ることができないため、複数のスレッドがある状況でこれを使っても意味がありません。戻り値は使われないため、単に None を返して構いません。プロファイル関数でエラーが起きると、その関数の設定が解除されます。

注釈

setprofile() は settrace() と同じトレースの仕組みを使います。トレース関数の内部 (例えばデバッガのブレークポイント) で setprofile() によって呼び出しを追跡する方法は、call_tracing() を参照してください。

Profile関数は 3 個の引数、frame、event、および arg を受け取る必要があります。frame は現在のスタックフレームです。event は文字列で、'call', 'return', 'c_call', 'c_return', 'c_exception' のどれかが渡されます。arg はイベントの種類によって異なります。

event には以下の意味があります。

'call': 関数が呼び出された(もしくは、何かのコードブロックに入った)。プロファイル関数が呼ばれる。 arg は None が渡される。
'return': 関数(あるいは別のコードブロック)から戻ろうとしている。プロファイル関数が呼ばれる。 arg は返されようとしている値、または、このイベントが例外が送出されることによって起こったなら None 。
'c_call': C 関数(拡張関数かビルトイン関数)が呼ばれようとしている。 arg は C 関数オブジェクト。
'c_return': C 関数から戻った。 arg は C の関数オブジェクト。
'c_exception': C 関数が例外を発生させた。 arg は C の関数オブジェクト。

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

sys.setrecursionlimit(limit)¶

Python インタプリタの、スタックの最大の深さを limit に設定します。この制限は Python プログラムが無限に再帰し、 C スタックがオーバーフローしてクラッシュすることを防止するために設けられています。

limit の最大値はプラットフォームによって異なります。深い再帰処理が必要な場合にはプラットフォームがサポートしている範囲内でより大きな値を指定することができますが、この値が大きすぎればクラッシュするので注意が必要です。

現在の再帰の深さに対して新しい上限が低すぎる場合、RecursionError 例外を送出します。

バージョン 3.5.1 で変更: 現在の再帰の深さに対して新しい上限が低すぎる場合、RecursionError 例外を送出するようになりました。

sys.setswitchinterval(interval)¶: インタプリタのスレッド切り替え間隔を秒で指定します。この浮動小数点値が、並列に動作しているPythonスレッドに割り当てられたタイムスライスの理想的な処理時間です。特に長時間実行される内部関数やメソッドが実行されたとき、実際の値はより高くなることがあります。また、どのスレッドがスレッド切り替え間隔の終わりにスケジュールされる（次に実行される）かはオペレーティングシステムが決定します。インタプリタは自身のスケジューラを持ちません。

Added in version 3.2.

sys.settrace(tracefunc)¶

システムのトレース関数を設定します。 Python のソースコード用のデバッガを Python で実装するために使えます。この関数はスレッド固有です。複数のスレッドに対応するデバッガでは、デバッグする各スレッドで settrace() を使ってトレース関数を登録するか、threading.settrace() を使う必要があります。

トレース関数は frame、event、arg の 3 つの引数を受け取る必要があります。 frame は現在のスタックフレームです。 event は 'call'、'line'、'return'、'exception'、'opcode' のいずれかの文字列です。 arg はイベントの種類によって異なります。

trace 関数は (event に 'call' を渡された状態で) 新しいローカルスコープに入るたびに呼ばれます。この場合、新しいスコープで利用するローカルの trace 関数への参照か、そのスコープを trace しないのであれば None を返します。

ローカルのトレース関数は、自分自身、またはそのスコープの新しいローカルトレース関数として使う別の関数への参照を返す必要があります。

トレース関数でエラーが発生すると、settrace(None) を呼んだときと同様に、トレース関数の設定が解除されます。

注釈

トレース関数 (例えば settrace() で設定した関数) を呼び出している間、トレースは無効になります。再帰的なトレースについては call_tracing() を参照してください。

event には以下の意味があります。

'call': 関数が呼び出された(もしくは、何かのコードブロックに入った)。グローバルの trace 関数が呼ばれる。 arg は None が渡される。戻り値はローカルの trace 関数。
'line': インタープリタが新しいコード行を実行しようとするか、ループの条件を再評価しようとしています。ローカルのトレース関数を呼び出し、arg には None を渡します。戻り値で新しいローカルトレース関数を指定します。仕組みの詳しい説明は InternalDocs/code_objects.md を参照してください。フレームの f_trace_lines を False に設定すると、そのフレームの行ごとのイベントを無効にできます。
'return': 関数(あるいは別のコードブロック)から戻ろうとしている。ローカルの trace 関数が呼ばれる。 arg は返されようとしている値、または、このイベントが例外が送出されることによって起こったなら None 。 trace 関数の戻り値は無視される。
'exception': 例外が発生した。ローカルの trace 関数が呼ばれる。 arg は (exception, value, traceback) のタプル。戻り値は新しいローカルの trace 関数。
'opcode': インタープリタが新しいオペコードを実行しようとしています (オペコードについては dis を参照)。ローカルのトレース関数を呼び出し、arg には None を渡します。戻り値で新しいローカルトレース関数を指定します。オペコードごとのイベントはデフォルトでは発生しません。フレームの f_trace_opcodes を True に設定して、明示的に要求する必要があります。

例外が呼び出しチェインを辿って伝播していくことに注意してください。 'exception' イベントは各レベルで発生します。

より細かく制御するには、登録済みのトレース関数の戻り値による間接的な設定に頼らず、frame.f_trace = tracefunc と明示的に代入してトレース関数を設定できます。現在のフレームでトレース関数を有効にする場合にも、この代入が必要です。 settrace() は現在のフレームでは有効にしません。ただし、これが動作するには、実行時のトレース機構を有効にするため、settrace() でグローバルなトレース関数を登録しておく必要があります。同じトレース関数である必要はなく、例えば各フレームで単に None を返して直ちに自身を無効にする、オーバーヘッドの小さい関数でも構いません。

code と frame オブジェクトについては、標準型の階層を参照してください。

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

settrace() 関数は、デバッガ、プロファイラ、カバレッジツール等で使うためだけのものです。この関数の挙動は言語定義よりも実装プラットフォームの分野の問題で、全ての Python 実装で利用できるとは限りません。

バージョン 3.7 で変更: 'opcode' イベントを追加し、フレームに f_trace_lines 属性と f_trace_opcodes 属性を追加しました。

sys.set_asyncgen_hooks([firstiter] [, finalizer])¶

省略可能な 2 つのキーワード引数を受け取ります。それぞれ非同期ジェネレータイテレータを引数に取る呼び出し可能オブジェクトです。 firstiter は、非同期ジェネレータを初めて反復するときに呼び出されます。 finalizer は、非同期ジェネレータがガベージコレクションで回収されようとするときに呼び出されます。

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

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

内部の API は 2 つの呼び出しからなり、それぞれがイベントを発生させる必要があるため、監査イベントも 2 つ発生します。

Added in version 3.6: See PEP 525 for more details, and for a reference example of a finalizer method see the implementation of asyncio.Loop.shutdown_asyncgens in Lib/asyncio/base_events.py

注釈

この関数は暫定的に追加されました (詳しくは PEP 411 を参照)。

sys.set_coroutine_origin_tracking_depth(depth)¶

コルーチンの生成元の追跡を有効または無効にします。有効にすると、コルーチンオブジェクトの cr_origin 属性に、そのオブジェクトが作成された場所のトレースバックを表す (ファイル名、行番号、関数名) のタプルを並べたタプルが入ります。最も新しい呼び出しが先頭です。無効にすると、cr_origin は None になります。

有効にするには、ゼロより大きい depth を渡します。これが、情報を取得するフレーム数になります。無効にするには depth をゼロにします。

この設定はスレッド固有です。

Added in version 3.7.

注釈

この関数は暫定的に追加されました (詳しくは PEP 411 を参照)。デバッグ目的でのみ使ってください。

sys.activate_stack_trampoline(backend, /)¶

スタックプロファイラのトランポリンの backend を有効にします。サポートするバックエンドは "perf" だけです。

JIT が有効な場合、スタックトランポリンは有効にできません。

利用可能な環境: Linux.

Added in version 3.12.

参考

sys.deactivate_stack_trampoline()¶

現在のスタックプロファイラのトランポリンのバックエンドを無効にします。

スタックプロファイラが有効でなければ、この関数は何もしません。

利用可能な環境: Linux.

Added in version 3.12.

sys.is_stack_trampoline_active()¶: スタックプロファイラのトランポリンが有効なら True を返します。

利用可能な環境: Linux.

Added in version 3.12.

sys.remote_exec(pid, script)¶

指定した pid のリモートプロセスで、Python コードを含むファイル script を実行します。

この関数はすぐに戻り、対象プロセスのメインスレッドが次に実行可能なタイミングでコードを実行します。シグナルの処理に似た動作です。コードがいつ実行されたかを調べるインターフェースはありません。リモートプロセスが読み取ろうとするときまでファイルが存在し、上書きされていないことを、呼び出し側が保証する必要があります。

リモートプロセスは、ローカルプロセスと同じメジャー・マイナーバージョンの CPython インタープリタを実行している必要があります。どちらかのインタープリタがプレリリース (アルファ、ベータ、リリース候補) なら、両者のバージョンは完全に一致しなければなりません。

リモートデバッグの仕組みについてはリモートデバッグのアタッチプロトコルを参照してください。

When the code is executed in the remote process, an auditing event sys.remote_exec is raised with the pid and the path to the script file. This event is raised in the process that called sys.remote_exec().

リモートプロセスでスクリプトを実行するとき、そのプロセス内のパスを引数として監査イベント cpython.remote_debugger_script を発生させます。このイベントは、sys.remote_exec() を呼び出したプロセスではなく、リモートプロセスで発生します。

利用可能な環境: Unix, Windows.

Added in version 3.14: 詳しくは PEP 768 を参照してください。

sys._enablelegacywindowsfsencoding()¶

Python 3.6 より前のバージョンとの互換性を保つため、ファイルシステムのエンコーディングとエラーハンドラをそれぞれ 'mbcs' と 'replace' に変更します。

これは、Python の起動前に環境変数 PYTHONLEGACYWINDOWSFSENCODING を定義することと同じです。

sys.getfilesystemencoding() と sys.getfilesystemencodeerrors() も参照してください。

利用可能な環境: Windows.

注釈

Python の起動後にファイルシステムエンコーディングを変更するのは危険です。以前のエンコーディング自体や、それでエンコードしたパスが、どこかにキャッシュされている可能性があるためです。代わりに PYTHONLEGACYWINDOWSFSENCODING を使ってください。

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

バージョン 3.13 で非推奨、バージョン 3.16 で削除予定: 代わりに PYTHONLEGACYWINDOWSFSENCODING を使ってください。

sys.stdin¶

sys.stdout¶

sys.stderr¶

インタプリタが使用する、それぞれ標準入力、標準出力、および標準エラー出力のファイルオブジェクトです:

stdin は (input() の呼び出しも含む) すべての対話型入力に使われます。
stdout は print() および expression 文の出力と、input() のプロンプトに使用されます。
インタプリタ自身のプロンプトおよびエラーメッセージは stderr に出力されます。

これらのストリームは open() が返すような通常のテキストファイルです。引数は以下のように選択されます:

エンコーディングとエラー処理方式は、PyConfig.stdio_encoding と PyConfig.stdio_errors から初期化します。

On Windows, UTF-8 is used for the console device. Non-character devices such as disk files and pipes use the system locale encoding (i.e. the ANSI codepage). Non-console character devices such as NUL (i.e. where isatty() returns True) use the value of the console input and output codepages at startup, respectively for stdin and stdout/stderr. This defaults to the system locale encoding if the process is not initially attached to a console.

Python の起動前に環境変数 PYTHONLEGACYWINDOWSSTDIO を設定すると、コンソール固有の動作を変更できます。その場合は、ほかの文字デバイスと同じようにコンソールのコードページを使います。

すべてのプラットフォームで、Python の起動前に環境変数 PYTHONIOENCODING を設定するか、新しい -X utf8 コマンドラインオプションや環境変数 PYTHONUTF8 を使うことで、文字エンコーディングを変更できます。ただし Windows のコンソールでは、PYTHONLEGACYWINDOWSSTDIO も設定した場合にだけ適用されます。
対話的な場合、stdout ストリームは行バッファリングを使います。それ以外の場合は、通常のテキストファイルと同じブロックバッファリングを使います。 stderr ストリームはどちらの場合も行バッファリングです。 -u コマンドラインオプションを渡すか、環境変数 PYTHONUNBUFFERED を設定すると、両方のストリームのバッファリングを無効にできます。

バージョン 3.9 で変更: 非対話的な stderr が、完全バッファリングではなく行バッファリングになりました。

注釈

標準ストリームにバイナリーデータの読み書きを行うには下位のバイナリー buffer オブジェクトを使用してください。例えば bytes を stdout に書き出す場合は sys.stdout.buffer.write(b'abc') を使用してください。

ただし、ライブラリを作成していて、そのコードが実行される状況を制御できない場合は、標準ストリームが io.StringIO のような buffer 属性を持たないファイル類似オブジェクトに置き換えられている可能性に注意してください。

sys.__stdin__¶

sys.__stdout__¶

sys.__stderr__¶

それぞれ起動時の stdin, stderr, stdout の値を保存しています。終了処理時に利用されます。また、 sys.std* オブジェクトが(訳注:別のファイルライクオブジェクトに)リダイレクトされている場合でも、実際の標準ストリームへの出力に利用できます。

また、標準ストリームが壊れたオブジェクトに置き換えられた場合に、動作する実際のファイルを復元するために利用することもできます。しかし、明示的に置き換え前のストリームを保存しておき、そのオブジェクトを復元する事を推奨します。

注釈

一部の条件下では、stdin, stdout, stderr も、オリジナルの __stdin__, __stdout__, __stderr__ も None になることがあります。これはコンソールに接続しない Windows GUI アプリケーションや、pythonw で起動された Python アプリケーションでよく見られます。

sys.stdlib_module_names¶

標準ライブラリのモジュール名を表す文字列の frozenset です。

すべてのプラットフォームで同じ値です。一部のプラットフォームでは利用できないモジュールや、Python のビルド時に無効にしたモジュールも含みます。純粋な Python、組み込み、凍結、拡張のすべての種類のモジュールを含みます。テスト用のモジュールは含みません。

パッケージについては最上位のパッケージだけを含み、サブパッケージやサブモジュールは含みません。例えば email パッケージは含みますが、email.mime サブパッケージや email.message サブモジュールは含みません。

sys.builtin_module_names の一覧も参照してください。

Added in version 3.10.

sys.thread_info¶

スレッドの実装に関する情報が格納された named tuple です。

thread_info.name¶

スレッド実装の名前:

"nt": Windows スレッド
"pthread": POSIX スレッド
"pthread-stubs": スタブの POSIX スレッド (スレッドに対応していない WebAssembly プラットフォーム)
"solaris": Solaris スレッド

thread_info.lock¶

ロック実装の名前:

"semaphore": a lock uses a semaphore
"mutex+cond": a lock uses a mutex and a condition variable
None この情報が不明の場合

thread_info.version¶: スレッドライブラリの名前とバージョンです。文字列で、情報が不明なら None です。

Added in version 3.3.

sys.tracebacklimit¶: 捕捉されない例外が発生した時、出力されるトレースバック情報の最大レベル数を指定する整数値(デフォルト値は 1000)。 0 以下の値が設定された場合、トレースバック情報は出力されず例外型と例外値のみが出力されます。

sys.unraisablehook(unraisable, /)¶

送出不能な例外を処理します。

例外が発生しても Python がそれを処理する方法がない場合に呼び出されます。例えば、デストラクタが例外を送出した場合や、ガベージコレクション (gc.collect()) 中に例外が発生した場合です。

unraisable 引数は次の属性を持ちます:

exc_type: 例外の型。
exc_value: 例外の値。 None のこともあります。
exc_traceback: 例外のトレースバック。 None のこともあります。
err_msg: エラーメッセージ。 None のこともあります。
object: 例外の原因となったオブジェクト。 None のこともあります。

The default hook formats err_msg and object as: f'{err_msg}: {object!r}'; use "Exception ignored in" error message if err_msg is None.

sys.unraisablehook() を置き換えることで、送出不能な例外の処理を制御できます。

参考

捕捉されない例外を処理する excepthook()。

警告

独自のフックで exc_value を保存すると、循環参照が生じることがあります。例外が不要になったら、保存した参照を明示的にクリアして循環参照を解消してください。

独自のフックで object を保存すると、それが終了処理中のオブジェクトだった場合、そのオブジェクトを復活させる可能性があります。オブジェクトの復活を避けるため、独自のフックの完了後まで object を保持しないでください。

処理できない例外が発生すると、引数 hook、unraisable を持つ監査イベント sys.unraisablehook を発生させます。 unraisable オブジェクトは、フックに渡されるものと同じです。フックが設定されていなければ hook は None のことがあります。

Added in version 3.8.

sys.version¶: Python インタプリタのバージョン番号の他、ビルド番号や使用コンパイラなどの情報を示す文字列です。この文字列は Python 対話型インタプリタが起動した時に表示されます。バージョン情報はここから抜き出さずに、 version_info および platform が提供する関数を使って下さい。

sys.api_version¶

C API のバージョンで、C マクロ PYTHON_API_VERSION と同じ値です。後方互換性のために定義されています。

現在、この定数は新しい Python バージョンでも更新されないため、バージョンの判別には役立ちません。将来は変更される可能性があります。

sys.version_info¶: バージョン番号を示す 5 要素タプル:major, minor, micro, releaselevel, serial 。 releaselevel 以外は全て整数です。 releaselevel の値は、 'alpha', 'beta', 'candidate', 'final' の何れかです。 Python 2.0 の version_info は、 (2, 0, 0, 'final', 0) となります。構成要素には名前でもアクセスできるので、 sys.version_info[0] は sys.version_info.major と等価、などになります。

バージョン 3.1 で変更: 名前を使った要素アクセスがサポートされました。

sys.warnoptions¶: これは warnings の仕組みの実装の詳細です。この値を変更しないでください。警告の仕組みについて詳しくは warnings モジュールを参照してください。

sys.winver¶: Windows プラットフォームでレジストリキーを作るために使うバージョン番号です。 Python DLL の文字列リソース 1000 に格納されています。通常の値は、実行中の Python インタープリタのメジャー・マイナーバージョンです。 sys モジュールでは情報提供用に公開しており、この値を変更しても Python が使うレジストリキーは変わりません。

利用可能な環境: Windows.

sys.monitoring: コールバックの登録やモニタリングイベントの制御を行う関数と定数を含む名前空間です。詳しくは sys.monitoring を参照してください。

sys._xoptions¶

コマンドラインオプション -X で渡された様々な実装固有のフラグの辞書です。オプション名にはその値が明示されていればそれが、それ以外の場合は True がマップされます。例えば:

$ ./python -Xa=b -Xc
Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys._xoptions
{'a': 'b', 'c': True}

これは、-X で渡されたオプションにアクセスする CPython 固有の方法です。ほかの実装では別の方法で公開することも、まったく公開しないこともあります。

Added in version 3.2.

出典

[C99]

ISO/IEC 9899:1999. "Programming languages -- C." この標準のパブリックドラフトが参照できます: https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf。

`sys` --- システム固有のパラメーターと関数¶

前のトピックへ

次のトピックへ

このページ

sys --- システム固有のパラメーターと関数¶

`sys` --- システム固有のパラメーターと関数¶