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 的開頭（允許匯入該目錄中的模組作為頂層模組）。

引發一個帶引數 command 的 審計事件 cpython.run_command。

-m <module-name>

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

由於引數是 *module* 名稱，因此您不得給出副檔名 (.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

引發一個帶引數 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* 環境變數也會被忽略。

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

另請參閱

runpy.run_path()

直接在 Python 程式碼中可用的等效功能

如果沒有給出介面選項，則預設使用 -i，sys.argv[0] 是一個空字串 ("")，並且當前目錄會被新增到 sys.path 的開頭。此外，如果你的平臺可用，則會自動啟用製表符補全和歷史記錄編輯（請參閱 Readline 配置）。

另請參閱

呼叫直譯器

在 3.4 版本中更改: 自動啟用製表符補全和歷史記錄編輯。

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（隔離）選項。

-i

當指令碼作為第一個引數傳遞或使用 -c 選項時，即使 sys.stdin 似乎不是終端，也會在執行指令碼或命令後進入互動模式。不讀取 PYTHONSTARTUP 檔案。

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

-I

在隔離模式下執行 Python。這也意味著 -E、-P 和 -s 選項。

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

在 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（隔離）選項。

在 3.11 版本中新增。

-q

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

3.2 版本新增。

-R

啟用雜湊隨機化。 僅當 PYTHONHASHSEED 環境變數設定為 0 時，此選項才生效，因為預設情況下已啟用雜湊隨機化。

在以前的 Python 版本中，此選項會啟用雜湊隨機化，從而使 str 和 bytes 物件的 __hash__() 值使用不可預測的隨機值“加鹽”。 雖然它們在單個 Python 程序中保持不變，但在重複呼叫 Python 之間是不可預測的。

雜湊隨機化的目的是防止因精心選擇的輸入而導致拒絕服務，這些輸入利用字典構建的最壞情況效能，O(n2) 複雜度。 有關詳細資訊，請參閱 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.main()）。

-u

強制 stdout 和 stderr 流無緩衝。 此選項對 stdin 流無效。

另請參閱 PYTHONUNBUFFERED。

在 3.7 版本中更改: stdout 和 stderr 流的文字層現在是無緩衝的。

-v

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

在 3.10 版本中更改: 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 用於顯示每個匯入花費的時間。 它顯示模組名稱、累積時間（包括巢狀匯入）和自身時間（不包括巢狀匯入）。 請注意，其輸出在多執行緒應用程式中可能會中斷。 典型用法是 python3 -X importtime -c 'import asyncio'。另請參閱 PYTHONPROFILEIMPORTTIME。

    在 3.7 版本中加入。

  • -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。請注意，即使此標誌設定為 off，也始終使用 importlib_bootstrap 和 importlib_bootstrap_external 凍結的模組。另請參閱 PYTHON_FROZEN_MODULES。

    在 3.11 版本中新增。

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

    在 3.12 版本中加入。

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

    在 3.13 版本中加入。

  • -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 和 自由執行緒 CPython。

    在 3.13 版本中加入。

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

3.2 版本新增。

在 3.9 版本中更改: 刪除了 -X showalloccount 選項。

在 3.10 版本中更改: 刪除了 -X oldparser 選項。

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.1.5. 你不應該使用的選項

-J

保留供 Jython 使用。

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 選項。

也可以使用 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，則會使用隨機值來為 str 和 bytes 物件的雜湊值生成種子。

如果 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

定義 user base directory，該目錄用於計算 user site-packages directory 的路徑以及 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

如果將此環境變數設定為非空字串，Python 將顯示每個匯入所花費的時間。這等效於設定 -X importtime 選項。

在 3.7 版本中加入。

PYTHONASYNCIODEBUG

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

在 3.4 版本中新增。

PYTHONMALLOC

設定 Python 記憶體分配器和/或安裝除錯鉤子。

設定 Python 使用的記憶體分配器系列

安裝除錯鉤子

  • 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 像往常一樣覆蓋此流處理行為。

出於除錯目的，如果區域設定強制轉換啟用，或者在 Python 執行時初始化時，仍處於活動狀態的區域設定將觸發強制轉換，則設定 PYTHONCOERCECLOCALE=warn 會使 Python 在 stderr 上發出警告訊息。

另請注意，即使停用區域設定強制轉換，或在查詢合適的目標區域設定失敗時，PYTHONUTF8 仍將在傳統的基於 ASCII 的區域設定中預設啟用。必須停用這兩個功能，才能強制直譯器對系統介面使用 ASCII 而不是 UTF-8。

可用性：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_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

如果此變數設定為 1，直譯器將不會嘗試載入需要 curses 和 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 命令列選項，該選項優先於此變數，以及 無執行緒 CPython。

在 3.13 版本中加入。

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 版本中加入。