1. 命令列與環境

CPython 直譯器會掃描命令列和環境以獲取各種設定。

CPython 實現細節: 其他實現的命令列方案可能有所不同。有關更多資源，請參閱 其他實現。

1.1. 命令列

呼叫 Python 時，可以指定以下任何選項

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

當然，最常見的用例是簡單地呼叫一個指令碼

python myscript.py

1.1.1. 介面選項

直譯器介面類似於 UNIX shell，但提供了一些額外的呼叫方法

• 當標準輸入連線到 tty 裝置時呼叫，它會提示輸入命令並執行它們，直到讀取到 EOF（檔案結束符，在 UNIX 上可以使用 Ctrl-D 生成，在 Windows 上可以使用 Ctrl-Z, Enter 生成）。有關互動模式的更多資訊，請參閱 互動模式。

• 當使用檔名引數或將檔案作為標準輸入呼叫時，它會從該檔案中讀取並執行指令碼。

• 當使用目錄名引數呼叫時，它會從該目錄中讀取並執行一個適當命名的指令碼。

• 當使用 -c command 呼叫時，它會執行作為 command 給出的 Python 語句。此處 command 可以包含由換行符分隔的多個語句。前導空格在 Python 語句中很重要！

• 當使用 -m module-name 呼叫時，會在 Python 模組路徑中找到給定的模組並將其作為指令碼執行。

在非互動模式下，整個輸入在執行之前都會被解析。

一個介面選項會終止直譯器消耗的選項列表，所有後續引數都將進入 sys.argv – 請注意，第一個元素，下標零 (sys.argv[0])，是一個反映程式源的字串。

-c <command>

執行 command 中的 Python 程式碼。command 可以是一個或多個由換行符分隔的語句，並且像普通模組程式碼一樣具有重要的前導空格。

如果給出此選項，sys.argv 的第一個元素將是 "-c"，並且當前目錄將新增到 sys.path 的開頭（允許在該目錄中的模組作為頂級模組匯入）。

引發一個 審計事件 cpython.run_command，引數為 command。

3.14 版本中的變化: command 在執行前會自動取消縮排。

-m <module-name>

在 sys.path 中搜索指定模組，並將其內容作為 __main__ 模組執行。

由於引數是 模組 名稱，因此您不能給出副檔名（.py）。模組名稱應該是一個有效的絕對 Python 模組名稱，但實現可能並不總是強制執行此操作（例如，它可能允許您使用包含連字元的名稱）。

包名稱（包括名稱空間包）也允許使用。當提供包名稱而不是普通模組時，直譯器將執行 <pkg>.__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 # for details

引發一個 審計事件 cpython.run_module，引數為 module-name。

參見

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* 環境變數也被忽略。

引發一個 審計事件 cpython.run_file，引數為 filename。

參見

runpy.run_path()

等效功能直接可用於 Python 程式碼

如果沒有給出介面選項，則隱含 -i，sys.argv[0] 是一個空字串 ("")，並且當前目錄將新增到 sys.path 的開頭。此外，如果您的平臺支援，還會自動啟用 Tab 補全和歷史編輯（請參閱 Readline 配置）。

參見

呼叫直譯器

3.4 版本中的變化: 自動啟用 Tab 補全和歷史編輯。

1.1.2. 通用選項

-?

-h

--help

列印所有命令列選項和相應環境變數的簡短描述並退出。

--help-env

列印 Python 特有環境變數的簡短描述並退出。

在 3.11 版本中新增。

--help-xoptions

列印實現特定的 -X 選項的描述並退出。

在 3.11 版本中新增。

--help-all

列印完整的用法資訊並退出。

在 3.11 版本中新增。

-V

--version

列印 Python 版本號並退出。示例輸出可能如下

Python 3.8.0b2+

當給定兩次時，列印更多關於構建的資訊，例如

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

3.6 版本新增: -VV 選項。

1.1.3. 其他選項

-b

當將 bytes 或 bytearray 轉換為 str 而未指定編碼，或比較 bytes 或 bytearray 與 str，或比較 bytes 與 int 時，發出警告。當此選項給定兩次時（-bb），則發出錯誤。

3.5 版本中的變化: 也影響 bytes 與 int 的比較。

-B

如果給定，Python 在匯入源模組時不會嘗試寫入 .pyc 檔案。另請參閱 PYTHONDONTWRITEBYTECODE。

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

控制基於雜湊的 .pyc 檔案的驗證行為。參閱 快取位元組碼失效。當設定為 default 時，已檢查和未檢查的基於雜湊的位元組碼快取檔案將根據其預設語義進行驗證。當設定為 always 時，所有基於雜湊的 .pyc 檔案，無論是否已檢查，都將根據其對應的原始檔進行驗證。當設定為 never 時，基於雜湊的 .pyc 檔案將不根據其對應的原始檔進行驗證。

基於時間戳的 .pyc 檔案的語義不受此選項影響。

-d

開啟解析器除錯輸出（僅限專家）。另請參閱 PYTHONDEBUG 環境變數。

此選項需要 Python 的除錯構建，否則將被忽略。

-E

忽略所有可能已設定的 PYTHON* 環境變數，例如 PYTHONPATH 和 PYTHONHOME。

另請參閱 -P 和 -I (isolated) 選項。

-i

執行後進入互動模式。

在以下任何情況下，使用 -i 選項都將進入互動模式

• 當指令碼作為第一個引數傳遞時

• 當使用 -c 選項時

• 當使用 -m 選項時

即使 sys.stdin 似乎不是終端，互動模式也會啟動。PYTHONSTARTUP 檔案不會被讀取。

當指令碼引發異常時，這對於檢查全域性變數或堆疊跟蹤很有用。另請參閱 PYTHONINSPECT。

-I

在隔離模式下執行 Python。這也隱含了 -E、-P 和 -s 選項。

在隔離模式下，sys.path 既不包含指令碼目錄，也不包含使用者的 site-packages 目錄。所有 PYTHON* 環境變數也被忽略。可能會施加進一步的限制以防止使用者注入惡意程式碼。

在 3.4 版本加入。

-O

刪除斷言語句和所有依賴於 __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（隔離）選項。

在 3.11 版本中新增。

-q

即使在互動模式下，也不顯示版權和版本資訊。

在 3.2 版本加入。

-R

啟用雜湊隨機化。此選項僅在 PYTHONHASHSEED 環境變數設定為 random 以外的任何值時才有效，因為雜湊隨機化預設是啟用的。

在以前的 Python 版本中，此選項會啟用雜湊隨機化，因此字串和位元組物件的 __hash__() 值會以不可預測的隨機值“加鹽”。儘管它們在單個 Python 程序中保持不變，但在重複呼叫 Python 時它們是不可預測的。

雜湊隨機化旨在提供保護，以防止因精心選擇的輸入而導致的拒絕服務，這些輸入利用了字典構建的最壞情況效能，即 O(n²) 複雜度。有關詳細資訊，請參閱 http://ocert.org/advisories/ocert-2011-003.html。

PYTHONHASHSEED 允許您為雜湊種子金鑰設定固定值。

在 3.2.3 版中新增。

3.7 版本中的變化: 該選項不再被忽略。

-s

不要將 使用者 site-packages 目錄 新增到 sys.path。

另請參閱 PYTHONNOUSERSITE。

參見

PEP 370 – 每個使用者的 site-packages 目錄

-S

停用模組 site 的匯入及其對 sys.path 造成的 site 相關操作。如果 site 稍後被顯式匯入，也停用這些操作（如果您希望它們被觸發，請呼叫 site.main()）。

-u

強制標準輸出和標準錯誤流不緩衝。此選項對標準輸入流無效。

另請參閱 PYTHONUNBUFFERED。

3.7 版本中的變化: 標準輸出和標準錯誤流的文字層現在不緩衝。

-v

每次初始化模組時列印一條訊息，顯示其載入位置（檔名或內建模組）。如果給定兩次（-vv），則在搜尋模組時，為每個被檢查的檔案列印一條訊息。還提供退出時模組清理的資訊。

3.10 版本中的變化: site 模組報告正在處理的 site 特定路徑和 .pth 檔案。

另請參閱 PYTHONVERBOSE。

-W arg

警告控制。Python 的警告機制預設會將警告訊息列印到 sys.stderr。

最簡單的設定是無條件地對程序發出的所有警告（即使是預設情況下被忽略的警告）應用特定的操作

-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wall      # Same as -Walways
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

操作名稱可以根據需要縮寫，直譯器會將其解析為適當的操作名稱。例如，-Wi 與 -Wignore 相同。

引數的完整形式是

action:message:category:module:lineno

空欄位匹配所有值；可以省略尾隨的空欄位。例如 -W ignore::DeprecationWarning 會忽略所有 DeprecationWarning 警告。

action 欄位如上所述，但僅適用於與其餘欄位匹配的警告。

message 欄位必須匹配完整的警告訊息；此匹配不區分大小寫。

category 欄位匹配警告類別（例如：DeprecationWarning）。這必須是一個類名；匹配測試訊息的實際警告類別是否是指定警告類別的子類。

module 欄位匹配（完全限定的）模組名稱；此匹配區分大小寫。

lineno 欄位匹配行號，其中零匹配所有行號，因此等同於省略行號。

可以給出多個 -W 選項；當一個警告與多個選項匹配時，執行最後一個匹配選項的操作。無效的 -W 選項將被忽略（但是，當發出第一個警告時，會列印有關無效選項的警告訊息）。

警告也可以使用 PYTHONWARNINGS 環境變數和 Python 程式內的 warnings 模組來控制。例如，warnings.filterwarnings() 函式可用於對警告訊息使用正則表示式。

有關詳細資訊，請參閱 警告過濾器 和 描述警告過濾器。

-x

跳過源的第一行，允許使用非 Unix 形式的 #!cmd。這僅用於 DOS 特定的技巧。

-X

保留用於各種特定於實現的選項。CPython 目前定義了以下可能的值

• -X faulthandler 用於啟用 faulthandler。另請參閱 PYTHONFAULTHANDLER。

  在 3.3 版本加入。

• -X showrefcount 在程式結束或互動式直譯器中的每個語句之後，輸出總引用計數和使用的記憶體塊數量。這僅適用於 除錯版本。

  在 3.4 版本加入。

• -X tracemalloc 使用 tracemalloc 模組開始跟蹤 Python 記憶體分配。預設情況下，回溯中只儲存最新幀的跟蹤。使用 -X tracemalloc=NFRAME 開始跟蹤，回溯限制為 NFRAME 幀。有關更多資訊，請參閱 tracemalloc.start() 和 PYTHONTRACEMALLOC。

  在 3.4 版本加入。

• -X int_max_str_digits 配置 整數字符串轉換長度限制。另請參閱 PYTHONINTMAXSTRDIGITS。

  在 3.11 版本中新增。

• -X importtime 用於顯示每次匯入所需的時間。它顯示模組名稱、累積時間（包括巢狀匯入）和自身時間（不包括巢狀匯入）。請注意，其輸出在多執行緒應用程式中可能會中斷。典型用法是 python -X importtime -c 'import asyncio'。

  -X importtime=2 啟用額外輸出，指示匯入的模組何時已載入。在這種情況下，字串 cached 將在兩個時間列中列印。

  另請參閱 PYTHONPROFILEIMPORTTIME。

  在 3.7 版本加入。

  3.14 版本中的變化: 增加了 -X importtime=2 以跟蹤已載入模組的匯入，並將 1 和 2 之外的值保留供將來使用。

• -X dev: 啟用 Python 開發模式，引入預設情況下過於昂貴的額外執行時檢查。另請參閱 PYTHONDEVMODE。

  在 3.7 版本加入。

• -X utf8 啟用 Python UTF-8 模式。-X utf8=0 明確停用 Python UTF-8 模式（即使它原本會自動啟用）。另請參閱 PYTHONUTF8。

  在 3.7 版本加入。

• -X pycache_prefix=PATH 允許將 .pyc 檔案寫入以給定目錄為根的並行樹，而不是程式碼樹。另請參閱 PYTHONPYCACHEPREFIX。

  在 3.8 版本加入。

• -X warn_default_encoding 在開啟檔案時使用特定於區域設定的預設編碼時發出 EncodingWarning。另請參閱 PYTHONWARNDEFAULTENCODING。

  在 3.10 版本加入。

• -X no_debug_ranges 停用在程式碼物件中包含將額外位置資訊（結束行、開始列偏移量和結束列偏移量）對映到每個指令的表。這在需要更小的程式碼物件和 pyc 檔案以及在直譯器顯示回溯時抑制額外的視覺位置指示符時很有用。另請參閱 PYTHONNODEBUGRANGES。

  在 3.11 版本中新增。

• -X frozen_modules 決定匯入機制是否忽略凍結模組。值為 on 表示它們被匯入，off 表示它們被忽略。如果這是一個已安裝的 Python（正常情況），則預設值為 on。如果它正在開發中（從原始碼樹執行），則預設值為 off。請注意，importlib_bootstrap 和 importlib_bootstrap_external 凍結模組始終使用，即使此標誌設定為 off。另請參閱 PYTHON_FROZEN_MODULES。

  在 3.11 版本中新增。

• -X perf 啟用對 Linux perf 分析器的支援。提供此選項後，perf 分析器將能夠報告 Python 呼叫。此選項僅在某些平臺上可用，如果當前系統不支援，則不起作用。預設值為“off”。另請參閱 PYTHONPERFSUPPORT 和 Python 對 Linux perf 分析器的支援。

  3.12 新版功能.

• -X perf_jit 啟用對帶有 DWARF 支援的 Linux perf 分析器的支援。提供此選項後，perf 分析器將能夠使用 DWARF 資訊報告 Python 呼叫。此選項僅在某些平臺上可用，如果當前系統不支援，則不起作用。預設值為“off”。另請參閱 PYTHON_PERF_JIT_SUPPORT 和 Python 對 Linux perf 分析器的支援。

  在 3.13 版本加入。

• -X disable_remote_debug 停用 PEP 768 中描述的遠端除錯支援。這包括在另一個程序中排程程式碼執行的功能和在當前程序中接收程式碼執行的功能。

  此選項僅在某些平臺上可用，如果當前系統不支援，則不起作用。另請參閱 PYTHON_DISABLE_REMOTE_DEBUG 和 PEP 768。

  在 3.14 版本加入。

• -X cpu_count=n 覆蓋 os.cpu_count()、os.process_cpu_count() 和 multiprocessing.cpu_count()。n 必須大於或等於 1。此選項可能對需要限制容器系統 CPU 資源的使用者有用。另請參閱 PYTHON_CPU_COUNT。如果 n 是 default，則不覆蓋任何內容。

  在 3.13 版本加入。

• -X presite=package.module 指定一個模組，該模組應在 site 模組執行之前和 __main__ 模組存在之前匯入。因此，匯入的模組不是 __main__。這可用於在 Python 初始化早期執行程式碼。Python 需要 以除錯模式構建 才能存在此選項。另請參閱 PYTHON_PRESITE。

  在 3.13 版本加入。

• -X gil=0,1 分別強制停用或啟用 GIL。將值設定為 0 僅在配置了 --disable-gil 的構建中可用。另請參閱 PYTHON_GIL 和 Free-threaded CPython。

  在 3.13 版本加入。

• -X thread_inherit_context=0,1 使得 Thread 預設在啟動時使用 Thread.start() 呼叫者的上下文副本。否則，執行緒將以空上下文啟動。如果未設定，此選項的值在自由執行緒構建上預設為 1，否則為 0。另請參閱 PYTHON_THREAD_INHERIT_CONTEXT。

  在 3.14 版本加入。

• -X context_aware_warnings=0,1 使得 warnings.catch_warnings 上下文管理器使用 ContextVar 來儲存警告過濾器狀態。如果未設定，此選項的值在自由執行緒構建上預設為 1，否則為 0。另請參閱 PYTHON_CONTEXT_AWARE_WARNINGS。

  在 3.14 版本加入。

• -X tlbc=0,1 在配置了 --disable-gil 的構建中啟用（1，預設）或停用（0）執行緒區域性位元組碼。停用後，這也停用了專門化的直譯器。另請參閱 PYTHON_TLBC。

  在 3.14 版本加入。

它還允許傳遞任意值並透過 sys._xoptions 字典檢索它們。

在 3.2 版本加入。

3.9 版本中的變化: 刪除了 -X showalloccount 選項。

3.10 版本中的變化: 刪除了 -X oldparser 選項。

在 3.14 版中移除: -J 不再保留供 Jython 使用，現在沒有特殊含義。

1.1.4. 控制顏色

Python 直譯器預設配置為在某些情況下（例如顯示回溯時）使用顏色突出顯示輸出。可以透過設定不同的環境變數來控制此行為。

將環境變數 TERM 設定為 dumb 將停用顏色。

如果設定了 FORCE_COLOR 環境變數，則無論 TERM 的值如何，都將啟用顏色。這在 CI 系統上很有用，因為它們不是終端，但仍然可以顯示 ANSI 轉義序列。

如果設定了 NO_COLOR 環境變數，Python 將停用輸出中的所有顏色。這優先於 FORCE_COLOR。

所有這些環境變數也用於其他工具來控制顏色輸出。要僅在 Python 直譯器中控制顏色輸出，可以使用 PYTHON_COLORS 環境變數。此變數優先於 NO_COLOR，而 NO_COLOR 又優先於 FORCE_COLOR。

1.2. 環境變數

這些環境變數影響 Python 的行為，它們在命令列開關（除了 -E 或 -I）之前處理。通常，命令列開關在存在衝突時會覆蓋環境變數。

PYTHONHOME

更改標準 Python 庫的位置。預設情況下，庫會在 prefix/lib/pythonversion 和 exec_prefix/lib/pythonversion 中搜索，其中 prefix 和 exec_prefix 是與安裝相關的目錄，兩者都預設為 /usr/local。

當 PYTHONHOME 設定為單個目錄時，其值會替換 prefix 和 exec_prefix。要為這些指定不同的值，請將 PYTHONHOME 設定為 prefix:exec_prefix。

PYTHONPATH

擴充模組檔案的預設搜尋路徑。格式與 shell 的 PATH 相同：一個或多個由 os.pathsep 分隔的目錄路徑名（例如，Unix 上的冒號或 Windows 上的分號）。不存在的目錄將被靜默忽略。

除了普通目錄外，單獨的 PYTHONPATH 條目可以引用包含純 Python 模組（以原始碼或編譯形式）的 zip 檔案。擴充套件模組不能從 zip 檔案匯入。

預設搜尋路徑與安裝相關，但通常以 prefix/lib/pythonversion 開頭（請參閱上面的 PYTHONHOME）。它 總是 附加到 PYTHONPATH。

如上文 介面選項 所述，一個額外的目錄將被插入到搜尋路徑中，位於 PYTHONPATH 之前。搜尋路徑可以在 Python 程式內部作為變數 sys.path 進行操作。

PYTHONSAFEPATH

如果此項設定為非空字串，則不要在 sys.path 前面新增可能不安全的路徑：有關詳細資訊，請參閱 -P 選項。

在 3.11 版本中新增。

PYTHONPLATLIBDIR

如果此項設定為非空字串，它將覆蓋 sys.platlibdir 值。

在 3.9 版本中新增。

PYTHONSTARTUP

如果這是一個可讀檔案的名稱，那麼在該檔案中定義的 Python 命令將在互動模式下顯示第一個提示之前執行。該檔案在與互動式命令相同的名稱空間中執行，這樣在其中定義或匯入的物件就可以在互動式會話中無需限定地使用。你也可以在此檔案中更改提示符 sys.ps1 和 sys.ps2 以及鉤子 sys.__interactivehook__。

啟動時呼叫時，會引發一個 審計事件 cpython.run_startup，並以檔名作為引數。

PYTHONOPTIMIZE

如果此變數設定為非空字串，則等同於指定 -O 選項。如果設定為整數，則等同於多次指定 -O。

PYTHONBREAKPOINT

如果此變數已設定，它將使用點路徑表示法命名一個可呼叫物件。包含該可呼叫物件的模組將被匯入，然後該可呼叫物件將由 sys.breakpointhook() 的預設實現執行，而 sys.breakpointhook() 本身是由內建函式 breakpoint() 呼叫的。如果未設定，或設定為空字串，則等同於值“pdb.set_trace”。將其設定為字串“0”會導致 sys.breakpointhook() 的預設實現不執行任何操作，而是立即返回。

在 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 將在指定路徑下寫入 .pyc 檔案，而不是在源樹中的 __pycache__ 目錄中。這等同於指定 -X pycache_prefix=PATH 選項。

在 3.8 版本加入。

PYTHONHASHSEED

如果未設定此變數或將其設定為 random，則使用隨機值作為字串和位元組物件的雜湊種子。

如果 PYTHONHASHSEED 設定為整數值，則它被用作生成雜湊隨機化所涵蓋的型別的 hash() 的固定種子。

其目的是允許可重複的雜湊，例如用於直譯器本身的自測試，或允許一組 Python 程序共享雜湊值。

該整數必須是範圍 [0,4294967295] 內的十進位制數。指定值 0 將停用雜湊隨機化。

在 3.2.3 版中新增。

PYTHONINTMAXSTRDIGITS

如果此變數設定為整數，則它用於配置直譯器的全域性 整數字符串轉換長度限制。

在 3.11 版本中新增。

PYTHONIOENCODING

如果在執行直譯器之前設定此項，它將覆蓋用於 stdin/stdout/stderr 的編碼，語法為 encodingname:errorhandler。 encodingname 和 :errorhandler 兩部分都是可選的，其含義與 str.encode() 中的相同。

對於 stderr，:errorhandler 部分被忽略；處理程式將始終為 'backslashreplace'。

版本 3.4 中已更改: encodingname 部分現在是可選的。

版本 3.6 中已更改: 在 Windows 上，除非同時指定 PYTHONLEGACYWINDOWSSTDIO，否則此變數指定的編碼對於互動式控制檯緩衝區將被忽略。透過標準流重定向的檔案和管道不受影響。

PYTHONNOUSERSITE

如果設定了此變數，Python 將不會把 user site-packages directory 新增到 sys.path。

參見

PEP 370 – 每使用者 site-packages 目錄

PYTHONUSERBASE

定義了 使用者基本目錄，用於計算 使用者 site-packages 目錄 的路徑以及 python -m pip install --user 的 安裝路徑。

參見

PEP 370 – 每使用者 site-packages 目錄

PYTHONEXECUTABLE

如果設定了此環境變數，sys.argv[0] 將被設定為其值，而不是透過 C 執行時獲取的值。僅適用於 macOS。

PYTHONWARNINGS

這等同於 -W 選項。如果設定為逗號分隔的字串，則等同於多次指定 -W，其中列表後部的過濾器優先於列表前部的過濾器。

最簡單的設定是無條件地對程序發出的所有警告（即使是預設情況下被忽略的警告）應用特定的操作

PYTHONWARNINGS=default  # Warn once per call location
PYTHONWARNINGS=error    # Convert to exceptions
PYTHONWARNINGS=always   # Warn every time
PYTHONWARNINGS=all      # Same as PYTHONWARNINGS=always
PYTHONWARNINGS=module   # Warn once per calling module
PYTHONWARNINGS=once     # Warn once per Python process
PYTHONWARNINGS=ignore   # Never warn

有關詳細資訊，請參閱 警告過濾器 和 描述警告過濾器。

PYTHONFAULTHANDLER

如果此環境變數設定為非空字串，則在啟動時呼叫 faulthandler.enable()：為 SIGSEGV、SIGFPE、SIGABRT、SIGBUS 和 SIGILL 訊號安裝一個處理程式以轉儲 Python 回溯。這等同於 -X faulthandler 選項。

在 3.3 版本加入。

PYTHONTRACEMALLOC

如果此環境變數設定為非空字串，則使用 tracemalloc 模組開始跟蹤 Python 記憶體分配。變數的值是跟蹤回溯中儲存的最大幀數。例如，PYTHONTRACEMALLOC=1 只儲存最新的幀。有關更多資訊，請參閱 tracemalloc.start() 函式。這等同於設定 -X tracemalloc 選項。

在 3.4 版本加入。

PYTHONPROFILEIMPORTTIME

如果此環境變數設定為 1，Python 將顯示每次匯入所需的時間。如果設定為 2，Python 將包含已載入的匯入模組的輸出。這等同於設定 -X importtime 選項。

在 3.7 版本加入。

版本 3.14 中已更改: 添加了 PYTHONPROFILEIMPORTTIME=2 以跟蹤已載入模組的匯入。

PYTHONASYNCIODEBUG

如果此環境變數設定為非空字串，則啟用 asyncio 模組的 除錯模式。

在 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 相同，但也會安裝除錯鉤子。

在 3.6 版本加入。

版本 3.7 中已更改: 添加了 "default" 分配器。

PYTHONMALLOCSTATS

如果設定為非空字串，Python 將在每次建立新的 pymalloc 物件區域時和在關閉時列印 pymalloc 記憶體分配器 的統計資訊。

如果 PYTHONMALLOC 環境變數用於強制使用 C 庫的 malloc() 分配器，或者如果 Python 未配置 pymalloc 支援，則此變數將被忽略。

版本 3.6 中已更改: 此變數現在也可用於以釋出模式編譯的 Python。如果設定為空字串，則現在無效。

PYTHONLEGACYWINDOWSFSENCODING

如果設定為非空字串，則預設的 檔案系統編碼和錯誤處理程式 模式將分別恢復為 3.6 之前的值“mbcs”和“replace”。否則，將使用新的預設值“utf-8”和“surrogatepass”。

這也可以在執行時使用 sys._enablelegacywindowsfsencoding() 啟用。

可用性：Windows。

3.6 新增: 有關更多詳細資訊，請參閱 PEP 529。

PYTHONLEGACYWINDOWSSTDIO

如果設定為非空字串，則不使用新的控制檯讀取器和寫入器。這意味著 Unicode 字元將根據活動控制檯內碼表進行編碼，而不是使用 utf-8。

如果標準流被重定向（到檔案或管道）而不是引用控制檯緩衝區，則此變數將被忽略。

可用性：Windows。

在 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 在 stderr 上發出警告訊息，如果區域設定強制轉換被啟用，或者如果當 Python 執行時初始化時，一個 會 觸發強制轉換的區域設定仍然處於活動狀態。

另請注意，即使停用區域設定強制轉換，或者當它未能找到合適的區域設定時，PYTHONUTF8 在傳統的基於 ASCII 的區域設定中仍會預設啟用。必須同時停用這兩個功能才能強制直譯器使用 UTF-8 而不是 ASCII 作為系統介面。

可用性：Unix。

3.7 新增: 有關更多詳細資訊，請參閱 PEP 538。

PYTHONDEVMODE

如果此環境變數設定為非空字串，則啟用 Python 開發模式，引入額外的執行時檢查，這些檢查預設情況下啟用成本太高。這等同於設定 -X dev 選項。

在 3.7 版本加入。

PYTHONUTF8

如果設定為 1，則啟用 Python UTF-8 模式。

如果設定為 0，則停用 Python UTF-8 模式。

設定任何其他非空字串將在直譯器初始化期間導致錯誤。

在 3.7 版本加入。

PYTHONWARNDEFAULTENCODING

如果此環境變數設定為非空字串，則在使用特定於區域設定的預設編碼時發出 EncodingWarning。

有關詳細資訊，請參閱 選擇性 EncodingWarning。

在 3.10 版本加入。

PYTHONNODEBUGRANGES

如果設定了此變數，它將停用在程式碼物件中將額外位置資訊（結束行、開始列偏移量和結束列偏移量）對映到每個指令的表的包含。當需要更小的程式碼物件和 pyc 檔案以及在直譯器顯示回溯時抑制額外的視覺位置指示器時，這很有用。

在 3.11 版本中新增。

PYTHONPERFSUPPORT

如果此變數設定為非零值，它將啟用對 Linux perf 分析器的支援，以便它可以檢測到 Python 呼叫。

如果設定為 0，則停用 Linux perf 分析器支援。

另請參閱 -X perf 命令列選項和 Python 對 Linux perf 分析器的支援。

3.12 新版功能.

PYTHON_PERF_JIT_SUPPORT

如果此變數設定為非零值，它將啟用對 Linux perf 分析器的支援，以便它可以使用 DWARF 資訊檢測到 Python 呼叫。

如果設定為 0，則停用 Linux perf 分析器支援。

另請參閱 -X perf_jit 命令列選項和 Python 對 Linux perf 分析器的支援。

在 3.13 版本加入。

PYTHON_DISABLE_REMOTE_DEBUG

如果此變數設定為非空字串，它將停用 PEP 768 中描述的遠端除錯功能。這包括在另一個程序中排程程式碼執行的功能和在當前程序中接收程式碼執行的功能。

另請參閱 -X disable_remote_debug 命令列選項。

在 3.14 版本加入。

PYTHON_CPU_COUNT

如果此變數設定為正整數，它將覆蓋 os.cpu_count() 和 os.process_cpu_count() 的返回值。

另請參閱 -X cpu_count 命令列選項。

在 3.13 版本加入。

PYTHON_FROZEN_MODULES

如果此變數設定為 on 或 off，它將決定匯入機制是否忽略凍結模組。值為 on 表示它們被匯入，off 表示它們被忽略。對於非除錯版本（正常情況）預設為 on，對於除錯版本預設為 off。請注意，即使此標誌設定為 off，importlib_bootstrap 和 importlib_bootstrap_external 凍結模組也始終會被使用。

另請參閱 -X frozen_modules 命令列選項。

在 3.13 版本加入。

PYTHON_COLORS

如果此變數設定為 1，直譯器將對各種輸出進行著色。將其設定為 0 則停用此行為。另請參閱 控制顏色。

在 3.13 版本加入。

PYTHON_BASIC_REPL

如果此變數設定為任何值，直譯器將不會嘗試載入需要 readline 的基於 Python 的 REPL，而是使用傳統的基於解析器的 REPL。

在 3.13 版本加入。

PYTHON_HISTORY

此環境變數可用於設定 .python_history 檔案的位置（預設情況下，它位於使用者主目錄中的 .python_history）。

在 3.13 版本加入。

PYTHON_GIL

如果此變數設定為 1，則全域性直譯器鎖 (GIL) 將被強制啟用。將其設定為 0 則強制停用 GIL（需要使用 --disable-gil 構建選項配置 Python）。

另請參閱 -X gil 命令列選項，它優先於此變數，以及 Free-threaded CPython。

在 3.13 版本加入。

PYTHON_THREAD_INHERIT_CONTEXT

如果此變數設定為 1，則 Thread 預設情況下在啟動時會使用 Thread.start() 呼叫者的上下文副本。否則，新執行緒將以空上下文啟動。如果未設定，此變數在自由執行緒構建中預設為 1，否則為 0。另請參閱 -X thread_inherit_context。

在 3.14 版本加入。

PYTHON_CONTEXT_AWARE_WARNINGS

如果設定為 1，則 warnings.catch_warnings 上下文管理器將使用 ContextVar 來儲存警告過濾器狀態。如果未設定，此變數在自由執行緒構建中預設為 1，否則為 0。請參閱 -X context_aware_warnings。

在 3.14 版本加入。

PYTHON_JIT

在支援實驗性即時編譯的版本中，此變數可以在直譯器啟動時強制停用 (0) 或啟用 (1) JIT。

在 3.13 版本加入。

PYTHON_TLBC

如果設定為 1，則啟用執行緒區域性位元組碼。如果設定為 0，則停用執行緒區域性位元組碼和專用直譯器。僅適用於使用 --disable-gil 配置的版本。

另請參閱 -X tlbc 命令列選項。

在 3.14 版本加入。

1.2.1. 除錯模式變數

PYTHONDUMPREFS

如果設定了此變數，Python 將在直譯器關閉後轉儲仍然存活的物件和引用計數。

需要使用 --with-trace-refs 構建選項配置 Python。

PYTHONDUMPREFSFILE

如果設定了此變數，Python 將在直譯器關閉後轉儲仍然存活的物件和引用計數，並將其寫入以此環境變數值作為路徑的檔案中。

需要使用 --with-trace-refs 構建選項配置 Python。

在 3.11 版本中新增。

PYTHON_PRESITE

如果此變數設定為模組，則該模組將在直譯器生命週期的早期匯入，在 site 模組執行之前，以及 __main__ 模組建立之前。因此，匯入的模組不會被視為 __main__。

這可用於在 Python 初始化早期執行程式碼。

要匯入子模組，請使用 package.module 作為值，就像在 import 語句中一樣。

另請參閱 -X presite 命令列選項，它優先於此變數。

需要使用 --with-pydebug 構建選項配置 Python。

在 3.13 版本加入。