4. Sử dụng Python trên Windows

Tài liệu này nhằm mục đích cung cấp cái nhìn tổng quan về hành vi dành riêng cho Windows mà bạn nên biết khi sử dụng Python trên Microsoft Windows.

Không giống như hầu hết các hệ thống và dịch vụ Unix, Windows không bao gồm cài đặt Python được hệ thống hỗ trợ. Thay vào đó, Python có thể được lấy từ một số nhà phân phối, bao gồm cả trực tiếp từ nhóm CPython. Mỗi bản phân phối Python sẽ có những lợi ích và hạn chế riêng, tuy nhiên, tính nhất quán với các công cụ khác mà bạn đang sử dụng nhìn chung là một lợi ích đáng giá. Trước khi thực hiện quy trình được mô tả ở đây, chúng tôi khuyên bạn nên điều tra các công cụ hiện có của mình để xem liệu chúng có thể cung cấp trực tiếp Python hay không.

Để có được Python từ nhóm CPython, hãy sử dụng Trình quản lý cài đặt Python. Đây là một công cụ độc lập giúp Python có sẵn dưới dạng lệnh chung trên máy Windows của bạn, tích hợp với hệ thống và hỗ trợ cập nhật theo thời gian. Bạn có thể tải xuống Trình quản lý cài đặt Python từ python.org/downloads hoặc thông qua Microsoft Store app.

Sau khi bạn đã cài đặt Trình quản lý cài đặt Python, lệnh python chung có thể được sử dụng từ bất kỳ thiết bị đầu cuối nào để khởi chạy phiên bản Python mới nhất hiện tại của bạn. Phiên bản này có thể thay đổi theo thời gian khi bạn thêm hoặc xóa các phiên bản khác nhau và lệnh py list sẽ hiển thị phiên bản nào là hiện tại.

Nói chung, chúng tôi khuyên bạn nên tạo virtual environment cho từng dự án và chạy <env>\Scripts\Activate trong thiết bị đầu cuối của mình để sử dụng nó. Điều này mang lại sự tách biệt giữa các dự án, tính nhất quán theo thời gian và đảm bảo rằng các lệnh bổ sung được các gói thêm vào cũng có sẵn trong phiên của bạn. Tạo môi trường ảo bằng python -m venv <env path>.

Nếu các lệnh python hoặc py dường như không hoạt động, vui lòng xem phần Troubleshooting bên dưới. Đôi khi cần có thêm các bước thủ công để định cấu hình PC của bạn.

Ngoài việc sử dụng trình quản lý cài đặt Python, Python còn có thể được lấy dưới dạng gói NuGet. Xem Các gói nuget.org bên dưới để biết thêm thông tin về các gói này.

Các bản phân phối có thể nhúng là các gói Python tối thiểu phù hợp để nhúng vào các ứng dụng lớn hơn. Chúng có thể được cài đặt bằng trình quản lý cài đặt Python. Xem Gói có thể nhúng bên dưới để biết thêm thông tin về các gói này.

4.1. Trình quản lý cài đặt Python

4.1.1. Cài đặt

Trình quản lý cài đặt Python có thể được cài đặt từ Microsoft Store app hoặc tải xuống và cài đặt từ python.org/downloads. Hai phiên bản giống hệt nhau.

Để cài đặt qua Store, chỉ cần nhấp vào "Cài đặt". Sau khi hoàn thành, hãy mở terminal và gõ python để bắt đầu.

Để cài đặt tệp được tải xuống từ python.org, hãy nhấp đúp và chọn "Cài đặt" hoặc chạy Add-AppxPackage <path to MSIX> trong Windows Powershell.

Sau khi cài đặt, các lệnh python, py và pymanager sẽ khả dụng. Nếu bạn hiện có các bản cài đặt Python hoặc đã sửa đổi biến PATH, bạn có thể cần xóa chúng hoặc hoàn tác các sửa đổi. Xem Khắc phục sự cố để được trợ giúp thêm về cách sửa các lệnh không hoạt động.

Khi cài đặt thời gian chạy lần đầu tiên, bạn có thể sẽ được nhắc thêm thư mục vào PATH của mình. Đây là tùy chọn, nếu bạn thích sử dụng lệnh py, nhưng được cung cấp cho những người muốn có đầy đủ các bí danh (chẳng hạn như python3.14.exe). Thư mục sẽ là %LocalAppData%\Python\bin theo mặc định nhưng có thể được quản trị viên tùy chỉnh. Nhấp vào Bắt đầu và tìm kiếm "Chỉnh sửa biến môi trường cho tài khoản của bạn" trên trang cài đặt hệ thống để thêm đường dẫn.

Mỗi thời gian chạy Python mà bạn cài đặt sẽ có thư mục riêng dành cho các tập lệnh. Những thứ này cũng cần được thêm vào PATH nếu bạn muốn sử dụng chúng.

Trình quản lý cài đặt Python sẽ được tự động cập nhật lên các bản phát hành mới. Điều này không ảnh hưởng đến bất kỳ cài đặt thời gian chạy Python nào. Việc gỡ cài đặt trình quản lý cài đặt Python sẽ không gỡ cài đặt bất kỳ thời gian chạy Python nào.

Ví dụ: nếu bạn không thể cài đặt MSIX trong ngữ cảnh của mình thì bạn đang sử dụng phần mềm triển khai tự động không hỗ trợ phần mềm này hoặc đang nhắm mục tiêu Windows Server 2019, vui lòng xem Cài đặt nâng cao bên dưới để biết thêm thông tin.

4.1.2. Sử dụng cơ bản

Lệnh được đề xuất để khởi chạy Python là python, lệnh này sẽ khởi chạy phiên bản được yêu cầu bởi tập lệnh đang được khởi chạy, môi trường ảo đang hoạt động hoặc phiên bản được cài đặt mặc định, đây sẽ là bản phát hành ổn định mới nhất trừ khi được định cấu hình khác. Nếu không có phiên bản nào được yêu cầu cụ thể và không có thời gian chạy nào được cài đặt thì bản phát hành mới nhất hiện tại sẽ được cài đặt tự động.

Đối với tất cả các kịch bản liên quan đến nhiều phiên bản thời gian chạy, lệnh được khuyến nghị là py. Điều này có thể được sử dụng ở bất kỳ đâu thay cho python hoặc trình khởi chạy py.exe cũ hơn. Theo mặc định, py khớp với hành vi của python, nhưng cũng cho phép các tùy chọn dòng lệnh chọn một phiên bản cụ thể cũng như các lệnh phụ để quản lý cài đặt. Đây là những chi tiết dưới đây.

Bởi vì lệnh py có thể đã được phiên bản trước sử dụng nên cũng có một lệnh pymanager rõ ràng. Các bản cài đặt theo tập lệnh có ý định sử dụng trình quản lý cài đặt Python nên cân nhắc sử dụng pymanager, do khả năng gặp phải xung đột với các bản cài đặt hiện có sẽ thấp hơn. Sự khác biệt duy nhất giữa hai lệnh là khi chạy mà không có bất kỳ đối số nào: py sẽ khởi chạy trình thông dịch mặc định của bạn, trong khi pymanager sẽ hiển thị trợ giúp (pymanager exec ... cung cấp hành vi tương đương với py ...).

Mỗi lệnh này cũng có một phiên bản cửa sổ để tránh tạo cửa sổ bảng điều khiển. Đó là pyw, pythonw và pymanagerw. Lệnh python3 cũng được bao gồm bắt chước lệnh python. Nó nhằm mục đích ngăn chặn việc vô tình sử dụng lệnh POSIX điển hình trên Windows, nhưng không nhằm mục đích sử dụng hoặc khuyến nghị rộng rãi.

Để khởi chạy thời gian chạy mặc định của bạn, hãy chạy python hoặc py với các đối số bạn muốn chuyển vào thời gian chạy (chẳng hạn như tệp tập lệnh hoặc mô-đun để khởi chạy):

$> py
...
$> python my-script.py
...
$> py -m cái này
...

Thời gian chạy mặc định có thể được ghi đè bằng biến môi trường PYTHON_MANAGER_DEFAULT hoặc tệp cấu hình. Xem Cấu hình để biết thông tin về cài đặt cấu hình.

Để khởi chạy một thời gian chạy cụ thể, lệnh py chấp nhận tùy chọn -V:<TAG>. Tùy chọn này phải được chỉ định trước bất kỳ tùy chọn nào khác. Thẻ là một phần hoặc toàn bộ mã định danh cho thời gian chạy; đối với những người thuộc nhóm CPython, nó trông giống như một phiên bản, có thể có nền tảng này. Để tương thích, V: có thể bị bỏ qua trong trường hợp thẻ đề cập đến bản phát hành chính thức và bắt đầu bằng 3.

$> py -V:3.14 ...
$> py -V:3-arm64 ...

Thời gian chạy từ các nhà phân phối khác cũng có thể yêu cầu đưa vào company. Điều này phải được phân tách khỏi thẻ bằng dấu gạch chéo và có thể là tiền tố. Việc chỉ định công ty là tùy chọn khi nó là PythonCore và việc chỉ định thẻ là tùy chọn (nhưng không phải dấu gạch chéo) khi bạn muốn bản phát hành mới nhất từ ​​một công ty cụ thể.

$> py -V:Nhà phân phối\1.0 ...
$> py -V:phân phối/ ...

Nếu không có phiên bản nào được chỉ định nhưng tệp tập lệnh được chuyển, tập lệnh sẽ được kiểm tra để tìm shebang line. Đây là định dạng đặc biệt dành cho dòng đầu tiên trong file cho phép ghi đè lệnh. Xem Dòng Shebang để biết thêm thông tin. Khi không có dòng Shebang hoặc không thể giải quyết được, tập lệnh sẽ được khởi chạy với thời gian chạy mặc định.

Nếu bạn đang chạy trong một môi trường ảo đang hoạt động, chưa yêu cầu một phiên bản cụ thể và không có dòng shebang thì thời gian chạy mặc định sẽ là môi trường ảo đó. Trong trường hợp này, lệnh python có thể đã bị ghi đè và không có hoạt động kiểm tra nào xảy ra. Tuy nhiên, hành vi này đảm bảo rằng lệnh py có thể được sử dụng thay thế cho nhau.

Khi không có thời gian chạy nào được cài đặt, mọi lệnh khởi chạy sẽ cố gắng cài đặt phiên bản được yêu cầu và khởi chạy nó. Tuy nhiên, sau khi cài đặt bất kỳ phiên bản nào, chỉ có lệnh py exec ... và pymanager exec ... sẽ cài đặt nếu không có phiên bản được yêu cầu. Các dạng lệnh khác sẽ hiển thị lỗi và hướng dẫn bạn sử dụng py install trước.

4.1.3. Trợ giúp lệnh

Lệnh py help sẽ hiển thị danh sách đầy đủ các lệnh được hỗ trợ, cùng với các tùy chọn của chúng. Bất kỳ lệnh nào cũng có thể được chuyển qua tùy chọn -? để hiển thị trợ giúp hoặc tên của nó được chuyển tới py help.

$> xin giúp đỡ
$> py trợ giúp cài đặt
$> cài đặt py /?

Tất cả các lệnh đều hỗ trợ một số tùy chọn phổ biến, sẽ được hiển thị bởi py help. Các tùy chọn này phải được chỉ định sau bất kỳ lệnh phụ nào. Việc chỉ định -v hoặc --verbose sẽ tăng lượng đầu ra được hiển thị và -vv sẽ tăng thêm cho mục đích gỡ lỗi. Việc chuyển -q hoặc --quiet sẽ giảm sản lượng và -qq sẽ giảm thêm.

Tùy chọn --config=<PATH> cho phép chỉ định tệp cấu hình để ghi đè nhiều cài đặt cùng một lúc. Xem Cấu hình bên dưới để biết thêm thông tin về các tệp này.

4.1.4. Liệt kê thời gian chạy

$> danh sách py [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...]

Có thể xem danh sách thời gian chạy đã cài đặt bằng py list. Một bộ lọc có thể được thêm vào dưới dạng một hoặc nhiều thẻ (có hoặc không có mã xác định công ty) và mỗi bộ lọc có thể bao gồm tiền tố <, <=, >= hoặc > để giới hạn trong một phạm vi.

Một loạt các định dạng được hỗ trợ và có thể được chuyển dưới dạng tùy chọn --format=<FMT> hoặc -f <FMT>. Các định dạng bao gồm table (chế độ xem bảng thân thiện với người dùng), csv (bảng được phân tách bằng dấu phẩy), json (một blob JSON duy nhất), jsonl (một blob JSON cho mỗi kết quả), exe (chỉ đường dẫn thực thi), prefix (chỉ đường dẫn tiền tố).

Tùy chọn --one hoặc -1 chỉ hiển thị một kết quả duy nhất. Nếu bao gồm thời gian chạy mặc định thì nó sẽ là thời gian chạy mặc định. Nếu không, kết quả "tốt nhất" sẽ được hiển thị ("tốt nhất" được xác định một cách mơ hồ, nhưng thường sẽ là phiên bản mới nhất). Kết quả do py list --one <TAG> hiển thị sẽ khớp với thời gian chạy do py -V:<TAG> khởi chạy.

Tùy chọn --only-managed loại trừ các kết quả không được trình quản lý cài đặt Python cài đặt. Điều này hữu ích khi xác định thời gian chạy nào có thể được cập nhật hoặc gỡ cài đặt thông qua lệnh py.

Tùy chọn --online là viết tắt của việc truyền --source=<URL> với nguồn mặc định. Việc chuyển một trong hai tùy chọn này sẽ tìm kiếm chỉ mục trực tuyến về các thời gian chạy có thể được cài đặt. Kết quả do py list --online --one <TAG> hiển thị sẽ khớp với thời gian chạy sẽ được py install <TAG> cài đặt.

$> danh sách py --trực tuyến 3.14

Để tương thích với trình khởi chạy cũ, các lệnh --list, --list-paths, -0 và -0p (ví dụ: py -0p) được giữ lại. Chúng không cho phép các tùy chọn bổ sung và sẽ tạo ra đầu ra có định dạng cũ.

4.1.5. Cài đặt thời gian chạy

$> cài đặt py [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]

Phiên bản thời gian chạy mới có thể được thêm bằng py install. Một hoặc nhiều thẻ có thể được chỉ định và thẻ đặc biệt default có thể được sử dụng để chọn mặc định. Phạm vi không được hỗ trợ để cài đặt.

Tùy chọn --source=<URL> cho phép ghi đè chỉ mục trực tuyến được sử dụng để lấy thời gian chạy. Điều này có thể được sử dụng với chỉ mục ngoại tuyến, như được hiển thị trong Lượt cài đặt ngoại tuyến.

Việc chuyển --force sẽ bỏ qua mọi tệp được lưu trong bộ nhớ đệm và xóa mọi cài đặt hiện có để thay thế bằng tệp được chỉ định.

Việc vượt qua --update sẽ thay thế các lượt cài đặt hiện có nếu phiên bản mới mới hơn. Nếu không, họ sẽ bị bỏ lại. Nếu không có thẻ nào được cung cấp với --update, tất cả các lượt cài đặt do trình quản lý cài đặt Python quản lý sẽ được cập nhật nếu có phiên bản mới hơn. Các bản cập nhật sẽ xóa mọi sửa đổi được thực hiện đối với bản cài đặt, bao gồm các gói được cài đặt chung, nhưng môi trường ảo sẽ tiếp tục hoạt động.

Việc chuyển --dry-run sẽ tạo đầu ra và nhật ký nhưng sẽ không sửa đổi bất kỳ lượt cài đặt nào.

Việc chuyển --refresh sẽ cập nhật tất cả đăng ký cho thời gian chạy đã cài đặt. Điều này sẽ tạo lại các phím tắt menu Bắt đầu, khóa đăng ký và bí danh chung (chẳng hạn như python3.14.exe hoặc cho bất kỳ tập lệnh đã cài đặt nào). Chúng được tự động làm mới khi cài đặt bất kỳ thời gian chạy nào, nhưng có thể cần được làm mới theo cách thủ công sau khi cài đặt gói.

Ngoài các tùy chọn trên, tùy chọn --target sẽ trích xuất thời gian chạy vào thư mục được chỉ định thay vì thực hiện cài đặt thông thường. Điều này rất hữu ích cho việc nhúng thời gian chạy vào các ứng dụng lớn hơn. Không giống như cài đặt thông thường, py sẽ không nhận biết được thời gian chạy được trích xuất và sẽ không có menu Bắt đầu hoặc phím tắt nào khác được tạo. Để khởi chạy thời gian chạy, hãy thực thi trực tiếp tệp thực thi chính (thường là python.exe) trong thư mục đích.

$> cài đặt py ... [-t=|--target=<PATH>] <TAG>

Lệnh py exec sẽ cài đặt thời gian chạy được yêu cầu nếu nó chưa có. Điều này được kiểm soát bởi cấu hình automatic_install (PYTHON_MANAGER_AUTOMATIC_INSTALL) và được bật theo mặc định. Nếu không có thời gian chạy nào, tất cả các lệnh khởi chạy sẽ thực hiện cài đặt tự động nếu cài đặt cấu hình cho phép. Điều này nhằm đảm bảo trải nghiệm tốt cho người dùng mới, nhưng nhìn chung không nên dựa vào thay vì sử dụng lệnh py exec hoặc lệnh cài đặt rõ ràng.

4.1.6. Lượt cài đặt ngoại tuyến

Để thực hiện cài đặt Python ngoại tuyến, trước tiên bạn cần tạo chỉ mục ngoại tuyến trên máy có quyền truy cập mạng.

$> cài đặt py --download=<PATH> ... <TAG>...

Tùy chọn --download=<PATH> sẽ tải xuống các gói cho các thẻ được liệt kê và tạo một thư mục chứa chúng và tệp index.json phù hợp cho việc cài đặt sau này. Toàn bộ thư mục này có thể được chuyển sang máy ngoại tuyến và được sử dụng để cài đặt một hoặc nhiều thời gian chạy đi kèm:

$> cài đặt py --source="<PATH>\index.json" <TAG>...

Trình quản lý cài đặt Python có thể được cài đặt bằng cách tải xuống trình cài đặt của nó và di chuyển nó sang máy khác trước khi cài đặt.

Ngoài ra, các tệp ZIP trong thư mục chỉ mục ngoại tuyến có thể được chuyển sang máy khác và giải nén một cách đơn giản. Thao tác này sẽ không đăng ký cài đặt theo bất kỳ cách nào và do đó, nó phải được khởi chạy bằng cách tham chiếu trực tiếp các tệp thực thi trong thư mục được giải nén, nhưng đôi khi đây là cách tiếp cận thích hợp hơn trong trường hợp không thể hoặc không thuận tiện khi cài đặt trình quản lý cài đặt Python.

Bằng cách này, thời gian chạy Python có thể được cài đặt và quản lý trên máy mà không cần truy cập internet.

4.1.7. Gỡ cài đặt thời gian chạy

$> gỡ cài đặt py [-y|--yes] <TAG>...

Thời gian chạy có thể bị xóa bằng lệnh py uninstall. Một hoặc nhiều thẻ phải được chỉ định. Phạm vi không được hỗ trợ ở đây.

Tùy chọn --yes bỏ qua lời nhắc xác nhận trước khi gỡ cài đặt.

Thay vì chuyển các thẻ riêng lẻ, tùy chọn --purge có thể được chỉ định. Thao tác này sẽ xóa tất cả thời gian chạy do trình quản lý cài đặt Python quản lý, bao gồm dọn dẹp menu Bắt đầu, sổ đăng ký và mọi bộ nhớ đệm tải xuống. Thời gian chạy không được cài đặt bởi trình quản lý cài đặt Python sẽ không bị ảnh hưởng và các tệp cấu hình cũng không được tạo theo cách thủ công.

$> py gỡ cài đặt [-y|--yes] --purge

Trình quản lý cài đặt Python có thể được gỡ cài đặt thông qua trang cài đặt "Ứng dụng đã cài đặt" của Windows. Thao tác này không xóa bất kỳ thời gian chạy nào và chúng vẫn có thể sử dụng được, mặc dù các lệnh python và py chung sẽ bị xóa. Cài đặt lại trình quản lý cài đặt Python sẽ cho phép bạn quản lý lại các thời gian chạy này. Để dọn sạch hoàn toàn tất cả thời gian chạy Python, hãy chạy với --purge trước khi gỡ cài đặt trình quản lý cài đặt Python.

4.1.8. Cấu hình

Trình quản lý cài đặt Python được định cấu hình với hệ thống phân cấp các tệp cấu hình, biến môi trường, tùy chọn dòng lệnh và cài đặt đăng ký. Nói chung, các tệp cấu hình có khả năng định cấu hình mọi thứ, bao gồm cả vị trí của các tệp cấu hình khác, trong khi cài đặt đăng ký chỉ dành cho quản trị viên và sẽ ghi đè các tệp cấu hình. Tùy chọn dòng lệnh ghi đè tất cả các cài đặt khác, nhưng không phải tùy chọn nào cũng khả dụng.

Phần này sẽ mô tả các giá trị mặc định nhưng lưu ý rằng các bản cài đặt được sửa đổi hoặc ghi đè có thể giải quyết các cài đặt theo cách khác.

Tệp cấu hình chung có thể được quản trị viên định cấu hình và sẽ được đọc trước. Tệp cấu hình người dùng được lưu trữ tại %AppData%\Python\pymanager.json (lưu ý rằng vị trí này nằm dưới Roaming, không phải Local) và được đọc tiếp theo, ghi đè mọi cài đặt từ các tệp trước đó. Tệp cấu hình bổ sung có thể được chỉ định làm biến môi trường PYTHON_MANAGER_CONFIG hoặc tùy chọn dòng lệnh --config (nhưng không phải cả hai). Những vị trí này có thể được sửa đổi bằng các tùy chọn tùy chỉnh quản trị được liệt kê sau.

Các cài đặt sau đây được coi là có thể được sửa đổi trong sử dụng bình thường. Các phần sau liệt kê những mục dành cho việc tùy chỉnh quản trị.

Tùy chọn cấu hình tiêu chuẩn

Khóa cấu hình	Biến môi trường	Mô tả
default_tag	PYTHON_MANAGER_DEFAULT	Phiên bản mặc định ưa thích để khởi chạy hoặc cài đặt. Theo mặc định, đây được hiểu là phiên bản chưa phát hành trước mới nhất của nhóm CPython.
default_platform	PYTHON_MANAGER_DEFAULT_PLATFORM	Nền tảng mặc định ưa thích để khởi chạy hoặc cài đặt. Điều này được coi là hậu tố cho thẻ được chỉ định, chẳng hạn như py -V:3.14 muốn cài đặt cho 3.14-64 nếu nó tồn tại (và default_platform là -64), nhưng sẽ sử dụng 3.14 nếu không có cài đặt được gắn thẻ nào tồn tại.
logs_dir	PYTHON_MANAGER_LOGS	Vị trí nơi các tệp nhật ký được ghi. Theo mặc định, %TEMP%.
automatic_install	PYTHON_MANAGER_AUTOMATIC_INSTALL	Đúng để cho phép cài đặt tự động khi sử dụng py exec để khởi chạy (hoặc py khi chưa cài đặt thời gian chạy nào). Các lệnh khác sẽ không tự động cài đặt, bất kể cài đặt này. Theo mặc định, đúng.
include_unmanaged	PYTHON_MANAGER_INCLUDE_UNMANAGED	Đúng để cho phép liệt kê và khởi chạy các thời gian chạy chưa được trình quản lý cài đặt Python cài đặt hoặc sai để loại trừ chúng. Theo mặc định, đúng.
shebang_can_run_anything	PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING	Đúng để cho phép các shebang trong tệp .py khởi chạy các ứng dụng không phải là thời gian chạy Python hoặc sai để ngăn chặn điều đó. Theo mặc định, đúng.
log_level	PYMANAGER_VERBOSE, PYMANAGER_DEBUG	Đặt mức đầu ra mặc định (0-50). Theo mặc định là 20. Giá trị thấp hơn sẽ tạo ra nhiều đầu ra hơn. Các biến môi trường là boolean và có thể tạo ra đầu ra bổ sung trong quá trình khởi động mà sau đó bị cấu hình khác chặn lại.
confirm	PYTHON_MANAGER_CONFIRM	Đúng để xác nhận một số hành động nhất định trước khi thực hiện chúng (chẳng hạn như gỡ cài đặt) hoặc sai để bỏ qua xác nhận. Theo mặc định, đúng.
install.source	PYTHON_MANAGER_SOURCE_URL	Ghi đè nguồn cấp dữ liệu chỉ mục để nhận được lượt cài đặt mới từ đó.
install.enable_entrypoints	(không có)	Đúng để tạo các lệnh chung cho các gói đã cài đặt (chẳng hạn như pip.exe). Chúng được xác định bởi chính các gói. Nếu được đặt thành sai, chỉ trình thông dịch Python mới tạo các lệnh chung. Theo mặc định, đúng. Bạn nên chạy py install --refresh sau khi thay đổi cài đặt này.
list.format	PYTHON_MANAGER_LIST_FORMAT	Chỉ định định dạng mặc định được sử dụng bởi lệnh py list. Theo mặc định, table.
install_dir	(không có)	Chỉ định thư mục gốc mà thời gian chạy sẽ được cài đặt vào. Nếu bạn thay đổi cài đặt này, thời gian chạy đã cài đặt trước đó sẽ không sử dụng được trừ khi bạn di chuyển chúng đến vị trí mới.
global_dir	(không có)	Chỉ định thư mục lưu trữ các lệnh chung (chẳng hạn như python3.14.exe và pip.exe). Thư mục này nên được thêm vào PATH của bạn để cung cấp các lệnh từ thiết bị đầu cuối của bạn.
download_dir	(không có)	Chỉ định thư mục lưu trữ các tập tin đã tải xuống. Thư mục này là bộ nhớ đệm tạm thời và có thể được dọn sạch theo thời gian.

Tên có dấu chấm phải được lồng bên trong các đối tượng JSON, ví dụ: list.format sẽ được chỉ định là {"list": {"format": "table"}}.

4.1.9. Dòng Shebang

Nếu dòng đầu tiên của tệp tập lệnh bắt đầu bằng #! thì nó được gọi là dòng "shebang". Linux và các hệ điều hành tương tự Unix khác có hỗ trợ riêng cho các dòng như vậy và chúng thường được sử dụng trên các hệ thống như vậy để chỉ ra cách thực thi một tập lệnh. Các lệnh python và py cho phép sử dụng các phương tiện tương tự với các tập lệnh Python trên Windows.

Để cho phép các dòng shebang trong tập lệnh Python có thể di chuyển được giữa Unix và Windows, một số lệnh 'ảo' được hỗ trợ để chỉ định trình thông dịch nào sẽ sử dụng. Các lệnh ảo được hỗ trợ là:

• /usr/bin/env <ALIAS>

• /usr/bin/env -S <ALIAS>

• /usr/bin/<ALIAS>

• /usr/local/bin/<ALIAS>

• <ALIAS>

Ví dụ: nếu dòng đầu tiên của tập lệnh của bạn bắt đầu bằng

#! /usr/bin/python

Python mặc định hoặc môi trường ảo đang hoạt động sẽ được định vị và sử dụng. Vì nhiều tập lệnh Python được viết để hoạt động trên Unix sẽ có dòng này, bạn nên thấy rằng trình khởi chạy có thể sử dụng các tập lệnh này mà không cần sửa đổi. Nếu bạn đang viết một tập lệnh mới trên Windows mà bạn hy vọng sẽ hữu ích trên Unix, bạn nên sử dụng một trong các dòng Shebang bắt đầu bằng /usr.

Bất kỳ lệnh ảo nào ở trên đều có thể được thay thế <ALIAS> bằng bí danh từ thời gian chạy đã cài đặt. Nghĩa là, bất kỳ lệnh nào được tạo trong thư mục bí danh chung (mà bạn có thể đã thêm vào biến môi trường PATH của mình) đều có thể được sử dụng trong shebang, ngay cả khi nó không có trên PATH của bạn. Điều này cho phép sử dụng các shebang như /usr/bin/python3.12 để chọn thời gian chạy cụ thể.

Nếu không có thời gian chạy nào được cài đặt hoặc nếu cài đặt tự động được bật thì thời gian chạy được yêu cầu sẽ được cài đặt nếu cần. Xem Cấu hình để biết thông tin về cài đặt cấu hình.

Dạng /usr/bin/env của dòng Shebang cũng sẽ tìm kiếm biến môi trường PATH để tìm các lệnh không được nhận dạng. Điều này tương ứng với hoạt động của chương trình Unix env, chương trình này thực hiện cùng một tìm kiếm nhưng ưu tiên khởi chạy các lệnh Python đã biết. Cảnh báo có thể được hiển thị khi tìm kiếm các tệp thực thi tùy ý và tìm kiếm này có thể bị tắt bởi tùy chọn cấu hình shebang_can_run_anything.

Các dòng Shebang không khớp với bất kỳ mẫu nào được coi là đường dẫn thực thi Windows tuyệt đối hoặc tương đối với thư mục chứa tệp tập lệnh. Đây là sự tiện lợi cho các tập lệnh chỉ dành cho Windows, chẳng hạn như các tập lệnh được tạo bởi trình cài đặt, vì hành vi này không tương thích với các shell kiểu Unix. Các đường dẫn này có thể được trích dẫn và có thể bao gồm nhiều đối số, sau đó đường dẫn đến tập lệnh và mọi đối số bổ sung sẽ được thêm vào. Chức năng này có thể bị tắt bởi tùy chọn cấu hình shebang_can_run_anything.

Ghi chú

Hoạt động của shebang trong trình quản lý cài đặt Python khác một chút so với trình khởi chạy py.exe trước đó và các tùy chọn cấu hình cũ không còn được áp dụng. Nếu bạn đặc biệt phụ thuộc vào hành vi hoặc cấu hình cũ, chúng tôi khuyên bạn nên cài đặt legacy launcher. Theo mặc định, lệnh py của trình khởi chạy cũ sẽ ghi đè lệnh của PyManager và bạn sẽ cần sử dụng các lệnh pymanager để cài đặt và gỡ cài đặt.

4.1.10. Cài đặt nâng cao

Đối với các trường hợp không thể cài đặt MSIX, chẳng hạn như một số nền tảng phân phối quản trị cũ hơn, có sẵn MSI từ trang tải xuống python.org. Zz003zz này không có giao diện người dùng và chỉ có thể thực hiện cài đặt trên mỗi máy vào vị trí mặc định của nó trong Tệp chương trình. Nó sẽ cố gắng sửa đổi biến môi trường PATH của hệ thống để bao gồm vị trí cài đặt này, nhưng hãy đảm bảo xác thực điều này trên cấu hình của bạn.

Ghi chú

Windows Server 2019 là phiên bản Windows duy nhất được CPython hỗ trợ không hỗ trợ MSIX. Đối với Windows Server 2019, bạn nên sử dụng MSI.

Xin lưu ý rằng gói MSI không gói bất kỳ thời gian chạy nào và do đó không phù hợp để cài đặt vào môi trường ngoại tuyến mà không tạo chỉ mục cài đặt ngoại tuyến. Xem Lượt cài đặt ngoại tuyến và Cấu hình quản trị để biết thông tin về cách xử lý các tình huống này.

Thời gian chạy do MSI cài đặt được chia sẻ với thời gian chạy do MSIX cài đặt và tất cả chỉ dành cho mỗi người dùng. Trình quản lý cài đặt Python không hỗ trợ cài đặt thời gian chạy trên mỗi máy. Để mô phỏng cài đặt trên mỗi máy, bạn có thể sử dụng py install --target=<shared location> với tư cách quản trị viên và thêm các sửa đổi trên toàn hệ thống của riêng bạn vào PATH, sổ đăng ký hoặc menu Bắt đầu.

Khi MSIX được cài đặt nhưng các lệnh không có sẵn trong biến môi trường PATH, chúng có thể được tìm thấy trong %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km hoặc %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0, tùy thuộc vào việc nó được cài đặt từ python.org hay thông qua Windows Store. Không nên cố gắng chạy tệp thực thi trực tiếp từ Tệp chương trình.

Để cài đặt trình quản lý cài đặt Python theo chương trình, cách dễ nhất là sử dụng WinGet, được bao gồm trong tất cả các phiên bản Windows được hỗ trợ:

$> cài đặt cánh 9NQ7512CXL7T -e --accept-gói-thỏa thuận --disable-interactivity

# Optionally chạy trình kiểm tra cấu hình và chấp nhận mọi thay đổi
$> cài đặt py --configure -y

Để tải xuống trình quản lý cài đặt Python và cài đặt trên máy khác, lệnh WinGet sau sẽ tải các tệp được yêu cầu từ Cửa hàng về thư mục Tải xuống của bạn (thêm -d <location> để tùy chỉnh vị trí đầu ra). Điều này cũng tạo ra một tệp YAML có vẻ như không cần thiết, vì MSIX đã tải xuống có thể được cài đặt bằng cách khởi chạy hoặc sử dụng các lệnh bên dưới.

$> tải xuống winget 9NQ7512CXL7T -e --skip-license --accept-gói-thỏa thuận --accept-source-thỏa thuận

Để cài đặt hoặc gỡ cài đặt MSIX theo chương trình chỉ bằng PowerShell, bạn nên sử dụng các lệnh ghép ngắn PowerShell Add-AppxPackage và Remove-AppxPackage:

$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
...
$> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Loại bỏ gói Appx

Windows có thể tải xuống và cài đặt bản phát hành mới nhất bằng cách chuyển tệp AppInstaller tới lệnh Add-AppxPackage. Cài đặt này bằng MSIX trên python.org và chỉ được khuyến nghị cho những trường hợp không thể cài đặt qua Store (tương tác hoặc sử dụng WinGet).

$> Add-AppxPackage -AppInstallerFile https://www.python.org/ftp/python/pymanager/pymanager.appinstaller

Các công cụ và API khác cũng có thể được sử dụng để cung cấp gói MSIX cho tất cả người dùng trên máy, nhưng Python không coi đây là một kịch bản được hỗ trợ. Chúng tôi khuyên bạn nên xem xét lệnh ghép ngắn PowerShell Add-AppxProvisionedPackage, lớp Windows PackageManager gốc hoặc tài liệu và hỗ trợ cho công cụ triển khai của bạn.

Bất kể phương pháp cài đặt nào, người dùng vẫn cần phải cài đặt bản sao Python của riêng họ, vì không có cách nào để kích hoạt các lượt cài đặt đó mà không phải là người dùng đã đăng nhập. Khi sử dụng MSIX, phiên bản Python mới nhất sẽ có sẵn cho tất cả người dùng cài đặt mà không cần truy cập mạng.

Lưu ý rằng MSIX có thể tải xuống từ Cửa hàng và từ trang web Python hơi khác một chút và không thể cài đặt cùng lúc. Bất cứ khi nào có thể, chúng tôi khuyên bạn nên sử dụng các lệnh WinGet ở trên để tải xuống gói từ Cửa hàng nhằm giảm nguy cơ thiết lập các bản cài đặt xung đột. Không có hạn chế cấp phép nào đối với trình quản lý cài đặt Python có thể ngăn việc sử dụng gói Store theo cách này.

4.1.11. Cấu hình quản trị

Có một số tùy chọn có thể hữu ích cho quản trị viên trong việc ghi đè cấu hình của trình quản lý cài đặt Python. Chúng có thể được sử dụng để cung cấp bộ nhớ đệm cục bộ, vô hiệu hóa một số loại phím tắt nhất định, ghi đè nội dung đi kèm. Tất cả các tùy chọn cấu hình ở trên có thể được đặt, cũng như các tùy chọn bên dưới.

Các tùy chọn cấu hình có thể bị ghi đè trong sổ đăng ký bằng cách đặt các giá trị trong HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager, trong đó tên giá trị khớp với khóa cấu hình và loại giá trị là REG_SZ. Lưu ý rằng khóa này có thể được tùy chỉnh nhưng chỉ bằng cách sửa đổi tệp cấu hình lõi được phân phối bằng trình quản lý cài đặt Python. Tuy nhiên, chúng tôi khuyên bạn chỉ nên sử dụng các giá trị đăng ký để đặt base_config thành tệp JSON chứa toàn bộ các phần ghi đè. Ghi đè khóa đăng ký sẽ thay thế mọi cài đặt được định cấu hình khác, trong khi base_config cho phép người dùng sửa đổi thêm các cài đặt mà họ có thể cần.

Lưu ý rằng hầu hết các cài đặt có biến môi trường đều hỗ trợ các biến đó vì cài đặt mặc định của chúng chỉ định biến đó. Nếu bạn ghi đè chúng, biến môi trường sẽ không hoạt động nữa, trừ khi bạn ghi đè nó bằng một biến khác. Ví dụ: giá trị mặc định của confirm theo nghĩa đen là %PYTHON_MANAGER_CONFIRM%, giá trị này sẽ giải quyết biến khi tải. Nếu bạn ghi đè giá trị thành yes thì biến môi trường sẽ không còn được sử dụng nữa. Nếu bạn ghi đè giá trị thành %CONFIRM% thì biến môi trường đó sẽ được sử dụng thay thế.

Cài đặt cấu hình là đường dẫn được hiểu là liên quan đến thư mục chứa tệp cấu hình đã chỉ định chúng.

Tùy chọn cấu hình quản trị

Khóa cấu hình	Mô tả
base_config	Tệp cấu hình có mức độ ưu tiên cao nhất để đọc. Lưu ý rằng chỉ có tệp cấu hình tích hợp và sổ đăng ký mới có thể sửa đổi cài đặt này.
user_config	Tệp cấu hình thứ hai cần đọc.
additional_config	Tệp cấu hình thứ ba cần đọc.
registry_override_key	Vị trí đăng ký để kiểm tra ghi đè. Lưu ý rằng chỉ tệp cấu hình tích hợp mới có thể sửa đổi cài đặt này.
bundled_dir	Thư mục chỉ đọc chứa các tệp được lưu trong bộ nhớ đệm cục bộ.
install.fallback_source	Đường dẫn hoặc URL tới một chỉ mục để tham khảo khi không thể truy cập được chỉ mục chính.
install.enable_shortcut_kinds	Danh sách các loại phím tắt được phép sử dụng được phân tách bằng dấu phẩy (ví dụ: "pep514,start"). Các phím tắt đã bật vẫn có thể bị disable_shortcut_kinds tắt.
install.disable_shortcut_kinds	Danh sách các loại phím tắt được phân tách bằng dấu phẩy cần loại trừ (ví dụ: "pep514,start"). Các phím tắt bị tắt không được enable_shortcut_kinds kích hoạt lại.
install.hard_link_entrypoints	Đúng là sử dụng liên kết cứng cho các phím tắt chung để tiết kiệm dung lượng ổ đĩa. Nếu sai thì mỗi phím tắt thực thi sẽ được sao chép thay thế. Sau khi thay đổi cài đặt này, bạn phải chạy py install --refresh --force để cập nhật các lệnh hiện có. Theo mặc định, đúng. Việc tắt tính năng này có thể cần thiết để khắc phục sự cố hoặc hệ thống gặp sự cố với liên kết tệp.
pep514_root	Vị trí đăng ký để đọc và ghi PEP 514 mục vào. Theo mặc định, HKEY_CURRENT_USER\Software\Python.
start_folder	Thư mục menu bắt đầu để viết phím tắt vào. Theo mặc định, Python. Đường dẫn này liên quan đến thư mục Chương trình của người dùng.
virtual_env	Đường dẫn đến môi trường ảo đang hoạt động. Theo mặc định, đây là %VIRTUAL_ENV%, nhưng có thể được đặt trống để tắt tính năng phát hiện venv.
shebang_can_run_anything_silently	Đúng để ngăn chặn các cảnh báo hiển thị khi shebang khởi chạy một ứng dụng không phải là thời gian chạy Python.
source_settings	Ánh xạ từ nguồn URL tới các cài đặt cụ thể cho chỉ mục đó. Khi nhiều tệp cấu hình bao gồm phần này, cài đặt URL sẽ được thêm hoặc ghi đè nhưng cài đặt riêng lẻ sẽ không được hợp nhất. Các cài đặt này hiện chỉ dành cho index signatures.

4.1.12. Cài đặt các tệp nhị phân có luồng tự do

Added in version 3.13.

Các bản phân phối dựng sẵn của bản dựng theo luồng miễn phí có sẵn bằng cách cài đặt các thẻ có hậu tố t.

$> py cài đặt 3,14t
$> py cài đặt 3.14t-arm64
$> py cài đặt 3.14t-32

Điều này sẽ cài đặt và đăng ký như bình thường. Nếu bạn chưa cài đặt thời gian chạy nào khác thì python sẽ khởi chạy thời gian chạy này. Nếu không, bạn sẽ cần sử dụng py -V:3.14t ... hoặc, nếu bạn đã thêm thư mục bí danh chung vào biến môi trường PATH của mình, các lệnh python3.14t.exe.

4.1.13. Chữ ký chỉ mục

Added in version 26.2.

Các tập tin chỉ mục có thể được ký để phát hiện sự giả mạo. Chữ ký là một tệp danh mục có cùng URL với chỉ mục có .cat được thêm vào tên tệp. Tệp danh mục phải chứa hàm băm của tệp chỉ mục phù hợp và phải được ký bằng chữ ký Authenticode hợp lệ. Điều này cho phép công cụ tiêu chuẩn (trên Windows) tạo chữ ký và mọi chứng chỉ đều có thể được sử dụng miễn là hệ điều hành máy khách đã tin cậy cơ quan chứng nhận của nó (CA gốc).

Chữ ký chỉ mục chỉ được tải xuống và kiểm tra khi phần source_settings của cấu hình cục bộ bao gồm chỉ mục URL và requires_signature là đúng hoặc chỉ mục JSON chứa requires_signature được đặt thành đúng. Khi cài đặt tồn tại trong cấu hình cục bộ, ngay cả khi sai, cài đặt trong chỉ mục sẽ bị bỏ qua.

Ngoài việc yêu cầu chữ ký hợp lệ, cài đặt required_root_subject và required_publisher_subject có thể hạn chế hơn nữa các chữ ký được chấp nhận dựa trên các trường Chủ đề chứng chỉ. Bất kỳ thuộc tính nào được chỉ định trong cấu hình đều phải khớp với thuộc tính trong chứng chỉ (các thuộc tính bổ sung trong chứng chỉ sẽ bị bỏ qua). Các thuộc tính điển hình là CN= cho tên chung, O= cho đơn vị tổ chức và C= cho quốc gia của nhà xuất bản.

Cuối cùng, cài đặt required_publisher_eku cho phép yêu cầu Cách sử dụng khóa nâng cao cụ thể (EKU) đã được chỉ định cho chứng chỉ của nhà xuất bản. Ví dụ: EKU 1.3.6.1.5.5.7.3.3 chỉ ra rằng chứng chỉ được dùng để ký mã (ngược lại với xác thực máy chủ hoặc ứng dụng khách). Kết hợp với CA gốc cụ thể, điều này cung cấp một cơ chế khác để xác minh chữ ký hợp pháp.

Đây là phần source_settings mẫu từ tệp cấu hình. Trong trường hợp này, nhà xuất bản nguồn cấp dữ liệu được xác định duy nhất bằng sự kết hợp giữa gốc Xác minh danh tính Microsoft và EKU do gốc đó chỉ định. Chữ ký cho trường hợp này sẽ được tìm thấy tại https://www.python.org/ftp/python/index-windows.json.cat.

{
  "source_settings": {
    "https://www.python.org/ftp/python/index-windows.json": {
      "requires_signature": đúng,
      "required_root_subject": "CN=Cơ quan cấp chứng chỉ gốc xác minh danh tính của Microsoft 2020",
      "required_publisher_subject": "CN=Nền tảng phần mềm Python",
      "required_publisher_eku": "1.3.6.1.4.1.311.97.608394634.79987812.305991749.578777327"
    }
  }
}

Thay vào đó, các cài đặt tương tự có thể được chỉ định trong tệp index.json. Trong trường hợp này, gốc và EKU bị bỏ qua, nghĩa là chữ ký phải hợp lệ và có tên chung cụ thể trong chứng chỉ của nhà xuất bản, nhưng không sử dụng kiểm tra nào khác.

{
  "requires_signature": đúng,
  "required_publisher_subject": "CN=Nền tảng phần mềm Python",
  "phiên bản": [
    // ...
  ]
}

Khi cài đặt từ bên trong nguồn cấp dữ liệu được sử dụng, người dùng sẽ được thông báo và cài đặt được hiển thị trong tệp nhật ký hoặc đầu ra chi tiết. Bạn nên sao chép các cài đặt này vào tệp cấu hình cục bộ cho các nguồn cấp dữ liệu sẽ được sử dụng thường xuyên để các sửa đổi trái phép đối với nguồn cấp dữ liệu không thể vô hiệu hóa xác minh.

Không thể ghi đè vị trí của tệp chữ ký trong nguồn cấp dữ liệu hoặc thông qua tệp cấu hình. Quản trị viên có thể cung cấp source_settings của riêng họ trong tệp cấu hình bắt buộc (xem Cấu hình quản trị).

Nếu xác thực chữ ký không thành công, bạn sẽ được thông báo và nhắc tiếp tục. Khi xác nhận tương tác không được phép (ví dụ: vì --yes đã được chỉ định), nó sẽ luôn bị hủy. Để sử dụng nguồn cấp dữ liệu có cấu hình không hợp lệ trong trường hợp này, bạn phải cung cấp tệp cấu hình tắt tính năng kiểm tra chữ ký cho nguồn cấp dữ liệu đó.

"source_settings": {
  "https://www.example.com/feed-with-invalid-signature.json": {
    "requires_signature": sai
  }
}

4.1.14. Khắc phục sự cố

Nếu trình quản lý cài đặt Python của bạn có vẻ không hoạt động chính xác, vui lòng thực hiện các kiểm tra và sửa lỗi này để xem liệu nó có giúp ích hay không. Nếu không, vui lòng báo cáo sự cố tại our bug tracker, bao gồm mọi tệp nhật ký có liên quan (được ghi vào thư mục %TEMP% của bạn theo mặc định).

Khắc phục sự cố

triệu chứng	Những điều cần thử
python báo lỗi "không tìm thấy lệnh" hoặc mở ứng dụng Store khi tôi nhập lệnh vào thiết bị đầu cuối của mình.	Bạn có install the Python install manager không?
	Nhấp vào Bắt đầu, mở "Quản lý bí danh thực thi ứng dụng" và kiểm tra xem bí danh cho "Python (mặc định)" đã được bật hay chưa. Nếu đã có, hãy thử tắt và bật lại để làm mới lệnh. Các lệnh "Python (cửa sổ mặc định)" và "Trình quản lý cài đặt Python" cũng có thể cần được làm mới.
	Kiểm tra xem lệnh py và pymanager có hoạt động không.
	Đảm bảo biến PATH của bạn chứa mục nhập cho %UserProfile%\AppData\Local\Microsoft\WindowsApps. Hệ điều hành bao gồm mục này một lần theo mặc định, sau các đường dẫn người dùng khác. Nếu loại bỏ, các phím tắt sẽ không được tìm thấy.
py báo lỗi "không tìm thấy lệnh" khi tôi nhập lệnh vào thiết bị đầu cuối của mình.	Bạn có install the Python install manager không?
	Nhấp vào Bắt đầu, mở "Quản lý bí danh thực thi ứng dụng" và kiểm tra xem bí danh cho "Python (mặc định)" đã được bật hay chưa. Nếu đã có, hãy thử tắt và bật lại để làm mới lệnh. Các lệnh "Python (cửa sổ mặc định)" và "Trình quản lý cài đặt Python" cũng có thể cần được làm mới.
	Đảm bảo biến PATH của bạn chứa mục nhập cho %UserProfile%\AppData\Local\Microsoft\WindowsApps. Hệ điều hành bao gồm mục này một lần theo mặc định, sau các đường dẫn người dùng khác. Nếu loại bỏ, các phím tắt sẽ không được tìm thấy.
py báo lỗi "không thể mở tệp" khi tôi gõ lệnh trong thiết bị đầu cuối của mình.	Điều này thường có nghĩa là bạn đã cài đặt trình khởi chạy cũ và nó được ưu tiên hơn trình quản lý cài đặt Python. Để xóa, hãy nhấp vào Bắt đầu, mở "Ứng dụng đã cài đặt", tìm kiếm "Trình khởi chạy Python" và gỡ cài đặt nó.
python không khởi chạy cùng thời gian chạy với py	Nhấp vào Bắt đầu, mở "Ứng dụng đã cài đặt", tìm mọi thời gian chạy Python hiện có và xóa chúng hoặc Sửa đổi và tắt các tùy chọn PATH.
	Nhấp vào Bắt đầu, mở "Quản lý bí danh thực thi ứng dụng" và kiểm tra xem bí danh python.exe của bạn có được đặt thành "Python (mặc định)"
python và py không khởi chạy thời gian chạy mà tôi mong đợi	Kiểm tra biến môi trường PYTHON_MANAGER_DEFAULT hoặc cấu hình default_tag của bạn. Lệnh py list sẽ hiển thị mặc định của bạn dựa trên các cài đặt này.
	Các bản cài đặt được quản lý bởi trình quản lý cài đặt Python sẽ được chọn trước các bản cài đặt không được quản lý. Sử dụng py install để cài đặt thời gian chạy mà bạn mong đợi hoặc định cấu hình thẻ mặc định của bạn.
	Các bản cài đặt thử nghiệm và phát hành trước không được quản lý bởi trình quản lý cài đặt Python có thể được chọn trước các bản phát hành ổn định. Định cấu hình thẻ mặc định của bạn hoặc gỡ cài đặt thời gian chạy phát hành trước và cài đặt lại bằng py install.
pythonw hoặc pyw không khởi chạy cùng thời gian chạy như python hoặc py	Nhấp vào Bắt đầu, mở "Quản lý bí danh thực thi ứng dụng" và kiểm tra xem bí danh pythonw.exe và pyw.exe của bạn có nhất quán với các bí danh khác hay không.
pip báo lỗi "không tìm thấy lệnh" khi tôi nhập lệnh vào thiết bị đầu cuối của mình.	Bạn đã kích hoạt môi trường ảo chưa? Chạy tập lệnh .venv\Scripts\activate trong thiết bị đầu cuối của bạn để kích hoạt.
	Gói có thể có sẵn nhưng thiếu tệp thực thi được tạo. Thay vào đó, chúng tôi khuyên bạn nên sử dụng lệnh python -m pip. Chạy py install --refresh và đảm bảo rằng thư mục phím tắt chung nằm trên PATH (nó sẽ được hiển thị trong đầu ra lệnh nếu không có) sẽ cung cấp các lệnh như pip (và các gói đã cài đặt khác).
Tôi đã cài đặt gói có pip nhưng không tìm thấy lệnh của nó.	Bạn đã kích hoạt môi trường ảo chưa? Chạy tập lệnh .venv\Scripts\activate trong thiết bị đầu cuối của bạn để kích hoạt.
	Các gói mới không tự động có các phím tắt chung được tạo bởi trình quản lý cài đặt Python. Tương tự, các gói đã gỡ cài đặt sẽ không bị xóa các phím tắt. Chạy py install --refresh để cập nhật các phím tắt chung cho các gói mới cài đặt.
Nhập script-name.py vào terminal sẽ mở ra một cửa sổ mới.	Đây là một hạn chế đã biết của hệ điều hành. Chỉ định py trước tên tập lệnh, tạo một tệp bó chứa @py "%~dpn0.py" %* có cùng tên với tập lệnh hoặc cài đặt legacy launcher và chọn nó làm liên kết cho tập lệnh.
Kéo thả tệp vào tập lệnh không hoạt động	Đây là một hạn chế đã biết của hệ điều hành. Nó được hỗ trợ với legacy launcher hoặc với trình quản lý cài đặt Python khi được cài đặt từ MSI.
Tôi đã cài đặt trình quản lý cài đặt Python nhiều lần.	Có thể cài đặt từ Store hoặc WinGet, từ MSIX trên trang web Python và từ MSI, tất cả cùng một lúc. Tất cả chúng đều tương thích và sẽ chia sẻ cấu hình cũng như thời gian chạy.
	Xem phần Cài đặt nâng cao trước đó để biết các cách gỡ cài đặt trình quản lý cài đặt ngoài trang cài đặt Ứng dụng đã cài đặt (Thêm và Xóa Chương trình) thông thường.
Cài đặt py.ini cũ của tôi không còn hoạt động.	Trình quản lý cài đặt Python mới không còn hỗ trợ tệp cấu hình này hoặc các cài đặt của nó nữa nên nó sẽ bị bỏ qua. Xem Cấu hình để biết thông tin về cài đặt cấu hình.

4.2. Gói có thể nhúng

Added in version 3.5.

Bản phân phối được nhúng là tệp ZIP chứa môi trường Python tối thiểu. Nó được thiết kế để hoạt động như một phần của ứng dụng khác, thay vì được người dùng cuối truy cập trực tiếp.

Để cài đặt bản phân phối được nhúng, chúng tôi khuyên bạn nên sử dụng py install với tùy chọn --target:

$> cài đặt py 3.14-nhúng --target=<thư mục>

Khi được trích xuất, bản phân phối nhúng (gần như) bị cô lập hoàn toàn khỏi hệ thống của người dùng, bao gồm các biến môi trường, cài đặt đăng ký hệ thống và các gói đã cài đặt. Thư viện tiêu chuẩn được bao gồm dưới dạng các tệp .pyc được biên dịch trước và tối ưu hóa trong ZIP, đồng thời python3.dll, python313.dll, python.exe và pythonw.exe đều được cung cấp. Không bao gồm Tcl/tk (bao gồm tất cả những người phụ thuộc, chẳng hạn như Nhàn rỗi), pip và tài liệu Python.

Một tệp ._pth mặc định được bao gồm, điều này hạn chế hơn nữa các đường dẫn tìm kiếm mặc định (như được mô tả bên dưới trong Tìm mô-đun). Tệp này dành cho người nhúng để sửa đổi khi cần thiết.

Các gói của bên thứ ba phải được cài đặt bởi trình cài đặt ứng dụng cùng với bản phân phối được nhúng. Việc sử dụng pip để quản lý các phần phụ thuộc như đối với bản cài đặt Python thông thường không được hỗ trợ trong bản phân phối này, mặc dù nếu cẩn thận, có thể bao gồm và sử dụng pip để cập nhật tự động. Nói chung, các gói của bên thứ ba phải được coi là một phần của ứng dụng ("nhà cung cấp") để nhà phát triển có thể đảm bảo khả năng tương thích với các phiên bản mới hơn trước khi cung cấp bản cập nhật cho người dùng.

Hai trường hợp sử dụng được đề xuất cho bản phân phối này được mô tả bên dưới.

4.2.1. Ứng dụng Python

Một ứng dụng viết bằng Python không nhất thiết yêu cầu người dùng phải biết về thực tế đó. Bản phân phối nhúng có thể được sử dụng trong trường hợp này để đưa phiên bản Python riêng vào gói cài đặt. Tùy thuộc vào mức độ minh bạch của nó (hoặc ngược lại, mức độ chuyên nghiệp của nó), có hai lựa chọn.

Việc sử dụng một tệp thực thi chuyên dụng làm trình khởi chạy yêu cầu một số mã hóa nhưng mang lại trải nghiệm minh bạch nhất cho người dùng. Với trình khởi chạy tùy chỉnh, không có dấu hiệu rõ ràng nào cho thấy chương trình đang chạy trên Python: các biểu tượng có thể được tùy chỉnh, thông tin về công ty và phiên bản có thể được chỉ định cũng như các liên kết tệp hoạt động bình thường. Trong hầu hết các trường hợp, trình khởi chạy tùy chỉnh chỉ có thể gọi Py_Main bằng dòng lệnh được mã hóa cứng.

Cách tiếp cận đơn giản hơn là cung cấp một tệp bó hoặc lối tắt được tạo để gọi trực tiếp python.exe hoặc pythonw.exe với các đối số dòng lệnh bắt buộc. Trong trường hợp này, ứng dụng sẽ có vẻ là Python chứ không phải tên thật của nó và người dùng có thể gặp khó khăn khi phân biệt nó với các quy trình Python hoặc liên kết tệp đang chạy khác.

Với cách tiếp cận thứ hai, các gói nên được cài đặt dưới dạng thư mục cùng với tệp thực thi Python để đảm bảo chúng có sẵn trên đường dẫn. Với trình khởi chạy chuyên dụng, các gói có thể được đặt ở các vị trí khác vì có cơ hội chỉ định đường dẫn tìm kiếm trước khi khởi chạy ứng dụng.

4.2.2. Nhúng Python

Các ứng dụng được viết bằng mã gốc thường yêu cầu một số dạng ngôn ngữ kịch bản và bản phân phối Python nhúng có thể được sử dụng cho mục đích này. Nói chung, phần lớn ứng dụng ở dạng mã gốc và một số phần sẽ gọi python.exe hoặc trực tiếp sử dụng python3.dll. Trong cả hai trường hợp, việc trích xuất bản phân phối nhúng vào thư mục con của bản cài đặt ứng dụng là đủ để cung cấp trình thông dịch Python có thể tải được.

Đối với việc sử dụng ứng dụng, các gói có thể được cài đặt vào bất kỳ vị trí nào vì có cơ hội chỉ định đường dẫn tìm kiếm trước khi khởi chạy trình thông dịch. Mặt khác, không có sự khác biệt cơ bản giữa việc sử dụng bản phân phối nhúng và cài đặt thông thường.

4.3. Các gói nuget.org

Added in version 3.5.2.

Gói nuget.org là môi trường Python có kích thước thu nhỏ nhằm mục đích sử dụng trên các hệ thống xây dựng và tích hợp liên tục không có cài đặt Python trên toàn hệ thống. Mặc dù nuget là "trình quản lý gói cho .NET", nhưng nó cũng hoạt động hoàn toàn tốt đối với các gói chứa công cụ thời gian xây dựng.

Truy cập nuget.org để biết thông tin cập nhật nhất về cách sử dụng nuget. Phần sau đây là bản tóm tắt đầy đủ dành cho các nhà phát triển Python.

Công cụ dòng lệnh nuget.exe có thể được tải xuống trực tiếp từ https://aka.ms/nugetclidl, chẳng hạn bằng cách sử dụng Curl hoặc PowerShell. Với công cụ này, phiên bản Python mới nhất dành cho máy 64 bit hoặc 32 bit được cài đặt bằng cách sử dụng

nuget.exe cài đặt python -ExcludeVersion -OutputDirectory.
nuget.exe cài đặt pythonx86 -ExcludeVersion -OutputDirectory .

Để chọn một phiên bản cụ thể, hãy thêm -Version 3.x.y. Thư mục đầu ra có thể được thay đổi từ . và gói sẽ được cài đặt vào thư mục con. Theo mặc định, thư mục con được đặt tên giống với gói và nếu không có tùy chọn -ExcludeVersion, tên này sẽ bao gồm phiên bản cụ thể được cài đặt. Bên trong thư mục con là thư mục tools chứa cài đặt Python:

# Without -ExcludePhiên bản
> .\python.3.5.2\tools\python.exe -V
Python 3.5.2

# With -ExcludePhiên bản
> .\python\tools\python.exe -V
Python 3.5.2

Nói chung, các gói nuget không thể nâng cấp được và các phiên bản mới hơn phải được cài đặt song song và được tham chiếu bằng đường dẫn đầy đủ. Ngoài ra, hãy xóa thư mục gói theo cách thủ công và cài đặt lại. Nhiều hệ thống CI sẽ tự động thực hiện việc này nếu chúng không bảo toàn tệp giữa các bản dựng.

Bên cạnh thư mục tools là thư mục build\native. Tệp này chứa tệp thuộc tính MSBuild python.props có thể được sử dụng trong dự án C++ để tham chiếu quá trình cài đặt Python. Việc bao gồm các cài đặt sẽ tự động sử dụng các tiêu đề và nhập thư viện trong bản dựng của bạn.

Các trang thông tin gói trên nuget.org là www.nuget.org/packages/python cho phiên bản 64 bit, www.nuget.org/packages/pythonx86 cho phiên bản 32 bit và www.nuget.org/packages/pythonarm64 cho phiên bản ARM64

4.3.1. Gói luồng miễn phí

Added in version 3.13.

Các gói chứa các tệp nhị phân có luồng tự do được đặt tên là python-freethreaded cho phiên bản 64 bit, pythonx86-freethreaded cho phiên bản 32 bit và pythonarm64-freethreaded cho phiên bản ARM64. Các gói này chứa cả điểm vào python3.13t.exe và python.exe, cả hai đều chạy luồng miễn phí.

4.4. Các gói thay thế

Bên cạnh bản phân phối CPython tiêu chuẩn, còn có các gói được sửa đổi bao gồm chức năng bổ sung. Sau đây là danh sách các phiên bản phổ biến và các tính năng chính của chúng:

ActivePython

Trình cài đặt tương thích đa nền tảng, tài liệu, PyWin32

Anaconda

Các mô-đun khoa học phổ biến (như numpy, scipy và pandas) và trình quản lý gói conda.

Enthought Deployment Manager

"Trình quản lý gói và môi trường Python thế hệ tiếp theo".

Enthought trước đây đã cung cấp Canopy, nhưng nó reached end of life in 2016.

WinPython

Phân phối dành riêng cho Windows với các gói khoa học dựng sẵn và các công cụ để xây dựng gói.

Lưu ý rằng các gói này có thể không bao gồm các phiên bản mới nhất của Python hoặc các thư viện khác và không được nhóm Python cốt lõi duy trì hoặc hỗ trợ.

4.5. Các phiên bản Windows được hỗ trợ

Như được chỉ định trong PEP 11, bản phát hành Python chỉ hỗ trợ nền tảng Windows trong khi Microsoft coi nền tảng này được hỗ trợ mở rộng. Điều này có nghĩa là Python 3.14 hỗ trợ Windows 10 trở lên. Nếu bạn cần hỗ trợ Windows 7, vui lòng cài đặt Python 3.8. Nếu bạn yêu cầu hỗ trợ Windows 8.1, vui lòng cài đặt Python 3.12.

4.6. Loại bỏ giới hạn MAX_PATH

Windows trước đây có độ dài đường dẫn giới hạn ở mức 260 ký tự. Điều này có nghĩa là các đường dẫn dài hơn sẽ không được giải quyết và sẽ xảy ra lỗi.

Trong các phiên bản Windows mới nhất, giới hạn này có thể được mở rộng lên hơn 32.000 ký tự. Quản trị viên của bạn sẽ cần kích hoạt chính sách nhóm "Bật đường dẫn dài Win32" hoặc đặt LongPathsEnabled thành 1 trong khóa đăng ký HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem.

Điều này cho phép hàm open(), mô-đun os và hầu hết các chức năng đường dẫn khác chấp nhận và trả về các đường dẫn dài hơn 260 ký tự.

Sau khi thay đổi tùy chọn trên và khởi động lại, không cần cấu hình thêm.

4.7. chế độ UTF-8

Added in version 3.7.

Windows vẫn sử dụng các mã hóa cũ cho mã hóa hệ thống (Trang mã ANSI). Python sử dụng nó để mã hóa mặc định các tệp văn bản (ví dụ: locale.getencoding()).

Điều này có thể gây ra sự cố vì UTF-8 được sử dụng rộng rãi trên internet và hầu hết các hệ thống Unix, bao gồm WSL (Hệ thống con Windows cho Linux).

Bạn có thể sử dụng Python UTF-8 Mode để thay đổi mã hóa văn bản mặc định thành UTF-8. Bạn có thể kích hoạt Python UTF-8 Mode thông qua tùy chọn dòng lệnh -X utf8 hoặc biến môi trường PYTHONUTF8=1. Xem PYTHONUTF8 để bật chế độ UTF-8 và Trình quản lý cài đặt Python để biết cách sửa đổi các biến môi trường.

Khi Python UTF-8 Mode được bật, bạn vẫn có thể sử dụng mã hóa hệ thống (Trang mã ANSI) thông qua codec "mbcs".

Lưu ý rằng việc thêm PYTHONUTF8=1 vào các biến môi trường mặc định sẽ ảnh hưởng đến tất cả các ứng dụng Python 3.7+ trên hệ thống của bạn. Nếu bạn có bất kỳ ứng dụng Python 3.7+ nào dựa vào mã hóa hệ thống cũ, bạn nên tạm thời đặt biến môi trường hoặc sử dụng tùy chọn dòng lệnh -X utf8.

Ghi chú

Ngay cả khi chế độ UTF-8 bị tắt, Python vẫn sử dụng UTF-8 theo mặc định trên Windows cho:

• Console I/O bao gồm I/O tiêu chuẩn (xem PEP 528 để biết chi tiết).

• Zz000zz (xem PEP 529 để biết chi tiết).

4.8. Tìm mô-đun

Những ghi chú này bổ sung cho mô tả tại Việc khởi tạo đường dẫn tìm kiếm mô-đun sys.path bằng các ghi chú chi tiết về Windows.

Khi không tìm thấy tệp ._pth, đây là cách sys.path được điền trên Windows:

• Một mục trống được thêm vào đầu, tương ứng với thư mục hiện tại.

• Nếu biến môi trường PYTHONPATH tồn tại, như được mô tả trong Biến môi trường, các mục nhập của nó sẽ được thêm vào tiếp theo. Lưu ý rằng trên Windows, các đường dẫn trong biến này phải được phân tách bằng dấu chấm phẩy để phân biệt chúng với dấu hai chấm được sử dụng trong mã định danh ổ đĩa (C:\, v.v.).

• "Đường dẫn ứng dụng" bổ sung có thể được thêm vào sổ đăng ký dưới dạng khóa con của \SOFTWARE\Python\PythonCore{version}\PythonPath trong cả tổ ong HKEY_CURRENT_USER và HKEY_LOCAL_MACHINE. Các khóa con có chuỗi đường dẫn được phân cách bằng dấu chấm phẩy làm giá trị mặc định sẽ khiến mỗi đường dẫn được thêm vào sys.path. (Lưu ý rằng tất cả các trình cài đặt đã biết chỉ sử dụng HKLM, vì vậy HKCU thường trống.)

• Nếu biến môi trường PYTHONHOME được đặt, nó được coi là "Trang chủ Python". Mặt khác, đường dẫn của tệp thực thi Python chính được sử dụng để định vị "tệp mốc" (Lib\os.py hoặc pythonXY.zip) để suy ra "Trang chủ Python". Nếu tìm thấy nhà Python, các thư mục con có liên quan được thêm vào sys.path (Lib, plat-win, v.v.) sẽ dựa trên thư mục đó. Mặt khác, đường dẫn Python cốt lõi được xây dựng từ PythonPath được lưu trữ trong sổ đăng ký.

• Nếu không thể định vị Trang chủ Python, không có PYTHONPATH nào được chỉ định trong môi trường và không tìm thấy mục đăng ký nào thì đường dẫn mặc định với các mục tương đối sẽ được sử dụng (ví dụ: .\Lib;.\plat-win, v.v.).

Nếu tìm thấy tệp pyvenv.cfg cùng với tệp thực thi chính hoặc trong thư mục phía trên tệp thực thi một cấp, thì các biến thể sau sẽ được áp dụng:

• Nếu home là đường dẫn tuyệt đối và PYTHONHOME không được đặt, đường dẫn này sẽ được sử dụng thay cho đường dẫn đến tệp thực thi chính khi suy ra vị trí gốc.

Kết quả cuối cùng của tất cả điều này là:

• Khi chạy python.exe hoặc bất kỳ .exe nào khác trong thư mục Python chính (phiên bản đã cài đặt hoặc trực tiếp từ thư mục PCbuild), đường dẫn cốt lõi sẽ được suy ra và các đường dẫn cốt lõi trong sổ đăng ký sẽ bị bỏ qua. Các "đường dẫn ứng dụng" khác trong sổ đăng ký luôn được đọc.

• Khi Python được lưu trữ trong một .exe khác (thư mục khác, được nhúng qua COM, v.v.), "Trang chủ Python" sẽ không được suy ra, do đó đường dẫn cốt lõi từ sổ đăng ký sẽ được sử dụng. Các "đường dẫn ứng dụng" khác trong sổ đăng ký luôn được đọc.

• Nếu Python không thể tìm thấy nhà của nó và không có giá trị đăng ký (.exe bị đóng băng, một số thiết lập cài đặt rất lạ), bạn sẽ nhận được một đường dẫn với một số đường dẫn mặc định nhưng tương đối.

Đối với những người muốn gói Python vào ứng dụng hoặc bản phân phối của mình, lời khuyên sau sẽ ngăn xung đột với các bản cài đặt khác:

• Bao gồm tệp ._pth cùng với tệp thực thi của bạn có chứa các thư mục cần đưa vào. Điều này sẽ bỏ qua các đường dẫn được liệt kê trong sổ đăng ký và biến môi trường, đồng thời cũng bỏ qua site trừ khi import site được liệt kê.

• Nếu bạn đang tải python3.dll hoặc python37.dll trong tệp thực thi của riêng mình, hãy đặt rõ ràng PyConfig.module_search_paths trước Py_InitializeFromConfig().

• Xóa và/hoặc ghi đè PYTHONPATH và đặt PYTHONHOME trước khi khởi chạy python.exe từ ứng dụng của bạn.

• Nếu bạn không thể sử dụng các đề xuất trước đó (ví dụ: bạn là bản phân phối cho phép mọi người chạy trực tiếp python.exe), hãy đảm bảo rằng tệp mốc (Lib\os.py) tồn tại trong thư mục cài đặt của bạn. (Lưu ý rằng nó sẽ không được phát hiện trong tệp ZIP, nhưng thay vào đó, tệp ZIP có tên chính xác sẽ được phát hiện.)

Những điều này sẽ đảm bảo rằng các tệp trong quá trình cài đặt trên toàn hệ thống sẽ không được ưu tiên hơn bản sao của thư viện chuẩn đi kèm với ứng dụng của bạn. Nếu không, người dùng của bạn có thể gặp sự cố khi sử dụng ứng dụng của bạn. Lưu ý rằng đề xuất đầu tiên là tốt nhất, vì những đề xuất khác có thể vẫn dễ bị ảnh hưởng bởi các đường dẫn không chuẩn trong gói đăng ký và gói trang web của người dùng.

Thay đổi trong phiên bản 3.6: Thêm hỗ trợ tệp ._pth và xóa tùy chọn applocal khỏi pyvenv.cfg.

Thay đổi trong phiên bản 3.6: Thêm pythonXX.zip làm điểm mốc tiềm năng khi liền kề trực tiếp với tệp thực thi.

Sắp loại bỏ từ phiên bản 3.6: Các mô-đun được chỉ định trong sổ đăng ký theo Modules (không phải PythonPath) có thể được importlib.machinery.WindowsRegistryFinder nhập. Công cụ tìm này được kích hoạt trên Windows ở phiên bản 3.6.0 trở về trước nhưng có thể cần được thêm rõ ràng vào sys.meta_path trong tương lai.

4.9. Các mô-đun bổ sung

Mặc dù Python đặt mục tiêu có thể di động trên tất cả các nền tảng, nhưng vẫn có những tính năng chỉ có ở Windows. Có một số mô-đun, cả trong thư viện chuẩn và bên ngoài, cũng như các đoạn mã để sử dụng các tính năng này.

Các mô-đun tiêu chuẩn dành riêng cho Windows được ghi lại bằng Dịch vụ cụ thể của MS Windows.

4.9.1. PyWin32

Mô-đun PyWin32 của Mark Hammond là tập hợp các mô-đun để hỗ trợ nâng cao dành riêng cho Windows. Điều này bao gồm các tiện ích cho:

• Component Object Model (COM)

• Cuộc gọi Win32 API

• Đăng ký

• Nhật ký sự kiện

• Giao diện người dùng Microsoft Foundation Classes (MFC)

PythonWin là một ứng dụng MFC mẫu được cung cấp cùng với PyWin32. Nó là một IDE có thể nhúng được với trình gỡ lỗi tích hợp sẵn.

Xem thêm

Win32 How Do I...?

của Tim Golden

Python and COM

của David và Paul Boddie

4.9.2. cx_Freeze

cx_Freeze gói các tập lệnh Python vào các chương trình Windows có thể thực thi được (tệp *.exe). Khi thực hiện xong việc này, bạn có thể phân phối ứng dụng của mình mà không yêu cầu người dùng cài đặt Python.

4.10. Biên dịch Python trên Windows

Nếu bạn muốn tự biên dịch CPython, điều đầu tiên bạn nên làm là lấy source. Bạn có thể tải xuống nguồn của bản phát hành mới nhất hoặc chỉ cần lấy một checkout mới.

Cây nguồn chứa giải pháp xây dựng và các tệp dự án cho Microsoft Visual Studio, đây là trình biên dịch được sử dụng để xây dựng các bản phát hành Python chính thức. Những tập tin này nằm trong thư mục PCbuild.

Kiểm tra PCbuild/readme.txt để biết thông tin chung về quá trình xây dựng.

Đối với các mô-đun mở rộng, hãy tham khảo Xây dựng tiện ích mở rộng C và C++ trên Windows.

4.11. Trình cài đặt đầy đủ (không dùng nữa)

Sắp loại bỏ từ phiên bản 3.14: Trình cài đặt này không được dùng nữa kể từ phiên bản 3.14 và sẽ không được tạo cho Python 3.16 trở lên. Xem Trình quản lý cài đặt Python để biết trình cài đặt hiện đại.

4.11.1. Các bước cài đặt

Bốn trình cài đặt Python 3.14 có sẵn để tải xuống - hai trình cài đặt cho phiên bản 32-bit và 64-bit của trình thông dịch. Zz001zz là một bản tải xuống ban đầu nhỏ và nó sẽ tự động tải xuống các thành phần cần thiết nếu cần. Zz002zz bao gồm các thành phần cần thiết cho cài đặt mặc định và chỉ yêu cầu kết nối internet cho các tính năng tùy chọn. Xem Cài đặt mà không cần tải xuống để biết các cách khác để tránh tải xuống trong khi cài đặt.

Sau khi khởi động trình cài đặt, có thể chọn một trong hai tùy chọn:

Nếu bạn chọn "Cài đặt ngay":

• Bạn sẽ not cần phải là quản trị viên (trừ khi yêu cầu cập nhật hệ thống cho Thư viện thời gian chạy C hoặc bạn cài đặt Trình quản lý cài đặt Python cho tất cả người dùng)

• Python sẽ được cài đặt vào thư mục người dùng của bạn

• Zz000zz sẽ được cài đặt theo tùy chọn ở cuối trang đầu tiên

• Thư viện chuẩn, bộ thử nghiệm, trình khởi chạy và pip sẽ được cài đặt

• Nếu được chọn, thư mục cài đặt sẽ được thêm vào PATH của bạn

• Các phím tắt sẽ chỉ hiển thị cho người dùng hiện tại

Việc chọn "Tùy chỉnh cài đặt" sẽ cho phép bạn chọn các tính năng cần cài đặt, vị trí cài đặt và các tùy chọn khác hoặc hành động sau khi cài đặt. Để cài đặt các ký hiệu gỡ lỗi hoặc tệp nhị phân, bạn sẽ cần sử dụng tùy chọn này.

Để thực hiện cài đặt cho tất cả người dùng, bạn nên chọn "Tùy chỉnh cài đặt". Trong trường hợp này:

• Bạn có thể được yêu cầu cung cấp thông tin xác thực hoặc phê duyệt quản trị

• Python sẽ được cài đặt vào thư mục Program Files

• Zz000zz sẽ được cài đặt vào thư mục Windows

• Các tính năng tùy chọn có thể được lựa chọn trong quá trình cài đặt

• Thư viện chuẩn có thể được biên dịch trước thành mã byte

• Nếu được chọn, thư mục cài đặt sẽ được thêm vào hệ thống PATH

• Các phím tắt có sẵn cho tất cả người dùng

4.11.2. Loại bỏ giới hạn MAX_PATH

Windows trước đây có độ dài đường dẫn giới hạn ở mức 260 ký tự. Điều này có nghĩa là các đường dẫn dài hơn sẽ không được giải quyết và sẽ xảy ra lỗi.

Trong các phiên bản Windows mới nhất, giới hạn này có thể được mở rộng lên khoảng 32.000 ký tự. Quản trị viên của bạn sẽ cần kích hoạt chính sách nhóm "Bật đường dẫn dài Win32" hoặc đặt LongPathsEnabled thành 1 trong khóa đăng ký HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem.

Điều này cho phép hàm open(), mô-đun os và hầu hết các chức năng đường dẫn khác chấp nhận và trả về các đường dẫn dài hơn 260 ký tự.

Sau khi thay đổi tùy chọn trên, không cần cấu hình thêm.

Thay đổi trong phiên bản 3.6: Hỗ trợ đường dẫn dài đã được bật trong Python.

4.11.3. Cài đặt không có giao diện người dùng

Tất cả các tùy chọn có sẵn trong giao diện người dùng trình cài đặt cũng có thể được chỉ định từ dòng lệnh, cho phép trình cài đặt theo tập lệnh sao chép cài đặt trên nhiều máy mà không cần sự tương tác của người dùng. Các tùy chọn này cũng có thể được đặt mà không chặn giao diện người dùng để thay đổi một số cài đặt mặc định.

Các tùy chọn sau (được tìm thấy bằng cách thực thi trình cài đặt bằng /?) có thể được chuyển vào trình cài đặt:

Tên	Mô tả
/thụ động	để hiển thị tiến trình mà không yêu cầu sự tương tác của người dùng
/im lặng	để cài đặt/gỡ cài đặt mà không hiển thị bất kỳ giao diện người dùng nào
/đơn giản	để ngăn chặn việc tùy chỉnh của người dùng
/gỡ cài đặt	để xóa Python (không cần xác nhận)
/bố cục [thư mục]	để tải xuống trước tất cả các thành phần
/log [tên tệp]	để chỉ định vị trí tệp nhật ký

Tất cả các tùy chọn khác được chuyển dưới dạng name=value, trong đó giá trị thường là 0 để tắt một tính năng, 1 để bật một tính năng hoặc một đường dẫn. Danh sách đầy đủ các tùy chọn có sẵn được hiển thị bên dưới.

Tên	Mô tả	Mặc định
Cài đặtTất cảNgười dùng	Thực hiện cài đặt trên toàn hệ thống.	0
TargetDir	Thư mục cài đặt	Được chọn dựa trên InstallAllUsers
Mặc địnhTất cảNgười dùngTargetDir	Thư mục cài đặt mặc định cho tất cả người dùng cài đặt	%ProgramFiles%\Python X.Y hoặc %ProgramFiles(x86)%\Python X.Y
Mặc địnhJustForMeTargetDir	Thư mục cài đặt mặc định cho các bản cài đặt dành riêng cho tôi	%LocalAppData%\Programs\Python\PythonXY hoặc %LocalAppData%\Programs\Python\PythonXY-32 hoặc %LocalAppData%\Programs\Python\PythonXY-64
Mặc địnhTùy chỉnhTargetDir	Thư mục cài đặt tùy chỉnh mặc định được hiển thị trong giao diện người dùng	(trống)
Tệp liên kết	Tạo liên kết tập tin nếu trình khởi chạy cũng được cài đặt.	1
Biên dịchTất cả	Biên dịch tất cả các tệp .py thành .pyc.	0
Đường dẫn thêm vào	Thêm các thư mục cài đặt và Tập lệnh vào PATH và thêm .PY vào PATHEXT	0
Nối thêm đường dẫn	Nối các thư mục cài đặt và Tập lệnh vào PATH và thêm .PY vào PATHEXT	0
Phím tắt	Tạo lối tắt cho trình thông dịch, tài liệu và IDLE nếu được cài đặt.	1
Bao gồm_doc	Hướng dẫn cài đặt Python	1
Bao gồm_gỡ lỗi	Cài đặt nhị phân gỡ lỗi	0
Bao gồm_dev	Cài đặt các tiêu đề và thư viện dành cho nhà phát triển. Bỏ qua điều này có thể dẫn đến một cài đặt không sử dụng được.	1
Bao gồm_exe	Cài đặt python.exe và các file liên quan. Bỏ qua điều này có thể dẫn đến một cài đặt không sử dụng được.	1
Bao gồm_launcher	Cài đặt Trình quản lý cài đặt Python.	1
Cài đặtLauncherTất cả người dùng	Cài đặt launcher cho tất cả người dùng. Cũng yêu cầu Include_launcher được đặt thành 1	1
Bao gồm_lib	Cài đặt thư viện tiêu chuẩn và các mô-đun mở rộng. Bỏ qua điều này có thể dẫn đến một cài đặt không sử dụng được.	1
Bao gồm_pip	Cài đặt gói pip và setuptools	1
Bao gồm_ký hiệu	Cài đặt biểu tượng gỡ lỗi (*.pdb)	0
Bao gồm_tcltk	Cài đặt hỗ trợ Tcl/Tk và IDLE	1
Bao gồm_kiểm tra	Cài đặt bộ kiểm tra thư viện tiêu chuẩn	1
Bao gồm_công cụ	Cài đặt tập lệnh tiện ích	1
Chỉ trình khởi chạy	Chỉ cài đặt launcher. Điều này sẽ ghi đè hầu hết các tùy chọn khác.	0
Cài đặt đơn giản	Vô hiệu hóa hầu hết giao diện người dùng cài đặt	0
Mô tả cài đặt đơn giản	Một thông báo tùy chỉnh sẽ hiển thị khi sử dụng giao diện người dùng cài đặt đơn giản hóa.	(trống)

Ví dụ: để âm thầm cài đặt bản cài đặt Python mặc định trên toàn hệ thống, bạn có thể sử dụng lệnh sau (từ dấu nhắc lệnh nâng cao):

python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Bao gồm_test=0

Để cho phép người dùng dễ dàng cài đặt bản sao Python cá nhân mà không cần bộ kiểm tra, bạn có thể cung cấp một phím tắt bằng lệnh sau. Điều này sẽ hiển thị một trang ban đầu được đơn giản hóa và không cho phép tùy chỉnh:

python-3.9.0.exe InstallAllUsers=0 Bao gồm_launcher=0 Bao gồm_test=0
    SimpleInstall=1 SimpleInstallDescription="Chỉ dành cho tôi, không có bộ thử nghiệm."

(Lưu ý rằng việc bỏ qua trình khởi chạy cũng sẽ bỏ qua các liên kết tệp và chỉ được khuyến nghị cho các lượt cài đặt cho mỗi người dùng khi cũng có bản cài đặt trên toàn hệ thống bao gồm trình khởi chạy.)

Các tùy chọn được liệt kê ở trên cũng có thể được cung cấp trong tệp có tên unattend.xml cùng với tệp thực thi. Tệp này chỉ định danh sách các tùy chọn và giá trị. Khi một giá trị được cung cấp dưới dạng thuộc tính, nó sẽ được chuyển đổi thành số nếu có thể. Các giá trị được cung cấp dưới dạng văn bản thành phần luôn được để lại dưới dạng chuỗi. Tệp ví dụ này đặt các tùy chọn giống như ví dụ trước:

<Tùy chọn>
    <Option Name="InstallAllUsers" Value="no" />
    <Tên tùy chọn="Include_launcher" Value="0" />
    <Option Name="Include_test" Value="no" />
    <Option Name="SimpleInstall" Value="yes" />
    <Option Name="SimpleInstallDescription">Chỉ dành cho tôi, không có bộ thử nghiệm</Option>
</Tùy chọn>

4.11.4. Cài đặt mà không cần tải xuống

Vì một số tính năng của Python không có trong bản tải xuống trình cài đặt ban đầu nên việc chọn các tính năng đó có thể yêu cầu kết nối Internet. Để tránh nhu cầu này, tất cả các thành phần có thể có có thể được tải xuống theo yêu cầu để tạo một layout hoàn chỉnh không còn yêu cầu kết nối Internet bất kể các tính năng đã chọn. Lưu ý rằng bản tải xuống này có thể lớn hơn yêu cầu, nhưng khi có một số lượng lớn cài đặt sẽ được thực hiện thì việc có một bản sao được lưu vào bộ nhớ đệm cục bộ sẽ rất hữu ích.

Thực hiện lệnh sau từ Dấu nhắc Lệnh để tải xuống tất cả các tệp cần thiết có thể. Hãy nhớ thay thế python-3.9.0.exe bằng tên thật của trình cài đặt của bạn và tạo bố cục trong các thư mục riêng để tránh xung đột giữa các tệp có cùng tên.

python-3.9.0.exe /layout [thư mục đích tùy chọn]

Bạn cũng có thể chỉ định tùy chọn /quiet để ẩn hiển thị tiến trình.

4.11.5. Sửa đổi cài đặt

Sau khi cài đặt Python, bạn có thể thêm hoặc xóa các tính năng thông qua công cụ Chương trình và Tính năng là một phần của Windows. Chọn mục Python và chọn "Gỡ cài đặt/Thay đổi" để mở trình cài đặt ở chế độ bảo trì.

"Sửa đổi" cho phép bạn thêm hoặc xóa các tính năng bằng cách sửa đổi các hộp kiểm - các hộp kiểm không thay đổi sẽ không cài đặt hoặc xóa bất kỳ thứ gì. Một số tùy chọn không thể thay đổi trong chế độ này, chẳng hạn như thư mục cài đặt; để sửa đổi những thứ này, bạn cần phải gỡ bỏ rồi cài đặt lại hoàn toàn Python.

"Sửa chữa" sẽ xác minh tất cả các tệp cần được cài đặt bằng cài đặt hiện tại và thay thế bất kỳ tệp nào đã bị xóa hoặc sửa đổi.

"Gỡ cài đặt" sẽ xóa hoàn toàn Python, ngoại trừ Trình quản lý cài đặt Python, có mục riêng trong Chương trình và Tính năng.

4.11.6. Cài đặt các tệp nhị phân có luồng tự do

Added in version 3.13.

Để cài đặt các tệp nhị phân dựng sẵn có bật tính năng phân luồng miễn phí (xem PEP 703), bạn nên chọn "Tùy chỉnh cài đặt". Trang tùy chọn thứ hai bao gồm hộp kiểm "Tải xuống các tệp nhị phân có luồng miễn phí".

Việc chọn tùy chọn này sẽ tải xuống và cài đặt các tệp nhị phân bổ sung vào cùng vị trí với bản cài đặt Python chính. Tệp thực thi chính được gọi là python3.13t.exe và các tệp nhị phân khác nhận được hậu tố t hoặc hậu tố ABI đầy đủ. Các tệp nguồn Python và các phần phụ thuộc đi kèm của bên thứ ba được chia sẻ với bản cài đặt chính.

Phiên bản có luồng miễn phí được đăng ký dưới dạng bản cài đặt Python thông thường với thẻ 3.13t (với hậu tố -32 hoặc -arm64 như bình thường đối với các nền tảng đó). Điều này cho phép các công cụ khám phá nó và để Trình quản lý cài đặt Python hỗ trợ py.exe -3.13t. Lưu ý rằng trình khởi chạy sẽ hiểu py.exe -3 (hoặc shebang python3) là "bản cài đặt 3.x mới nhất", sẽ thích các tệp nhị phân có luồng tự do hơn các tệp nhị phân thông thường, trong khi py.exe -3.13 thì không. Nếu bạn sử dụng kiểu tùy chọn ngắn, bạn có thể không muốn cài đặt các tệp nhị phân có luồng tự do vào lúc này.

Để chỉ định tùy chọn cài đặt tại dòng lệnh, hãy sử dụng Include_freethreaded=1. Xem Cài đặt mà không cần tải xuống để biết hướng dẫn tải xuống trước các tệp nhị phân bổ sung để cài đặt ngoại tuyến. Các tùy chọn bao gồm các ký hiệu gỡ lỗi và tệp nhị phân cũng áp dụng cho các bản dựng có luồng tự do.

Các tệp nhị phân có luồng miễn phí cũng có sẵn on nuget.org.

4.12. Trình khởi chạy Python cho Windows (không được dùng nữa)

Sắp loại bỏ từ phiên bản 3.14: Trình khởi chạy và tài liệu này đã được thay thế bằng Trình quản lý cài đặt Python được mô tả ở trên. Điều này được bảo tồn tạm thời vì lợi ích lịch sử.

Added in version 3.3.

Trình khởi chạy Python dành cho Windows là một tiện ích hỗ trợ định vị và thực thi các phiên bản Python khác nhau. Nó cho phép các tập lệnh (hoặc dòng lệnh) biểu thị tùy chọn cho một phiên bản Python cụ thể và sẽ định vị và thực thi phiên bản đó.

Không giống như biến PATH, trình khởi chạy sẽ chọn chính xác phiên bản Python phù hợp nhất. Nó sẽ ưu tiên cài đặt cho mỗi người dùng hơn là cài đặt trên toàn hệ thống và sắp xếp thứ tự theo phiên bản ngôn ngữ hơn là sử dụng phiên bản được cài đặt gần đây nhất.

Trình khởi chạy ban đầu được chỉ định trong PEP 397.

4.12.1. Bắt đầu

4.12.1.1. Từ dòng lệnh

Thay đổi trong phiên bản 3.6.

Việc cài đặt Python 3.3 trở lên trên toàn hệ thống sẽ đưa trình khởi chạy vào PATH của bạn. Trình khởi chạy tương thích với tất cả các phiên bản Python có sẵn, vì vậy việc cài đặt phiên bản nào không quan trọng. Để kiểm tra xem trình khởi chạy có khả dụng hay không, hãy thực hiện lệnh sau trong Dấu nhắc lệnh

py

Bạn sẽ thấy rằng phiên bản Python mới nhất mà bạn đã cài đặt đã được khởi động - phiên bản này có thể được thoát như bình thường và mọi đối số dòng lệnh bổ sung được chỉ định sẽ được gửi trực tiếp tới Python.

Nếu bạn đã cài đặt nhiều phiên bản Python (ví dụ: 3.7 và 3.14), bạn sẽ nhận thấy rằng Python 3.14 đã được khởi động - để khởi chạy Python 3.7, hãy thử lệnh:

py -3,7

Nếu bạn muốn phiên bản Python 2 mới nhất mà bạn đã cài đặt, hãy thử lệnh:

py -2

Nếu bạn thấy lỗi sau thì có nghĩa là bạn chưa cài đặt trình khởi chạy:

'py' không được công nhận là lệnh nội bộ hoặc bên ngoài,
chương trình có thể hoạt động hoặc tập tin bó.

Lệnh:

py --list

hiển thị (các) phiên bản Python hiện được cài đặt.

Đối số -x.y là dạng rút gọn của đối số -V:Company/Tag, cho phép chọn thời gian chạy Python cụ thể, bao gồm cả những đối số có thể đến từ một nơi nào đó ngoài python.org. Mọi thời gian chạy được đăng ký bằng cách theo dõi PEP 514 đều có thể được phát hiện. Lệnh --list liệt kê tất cả thời gian chạy có sẵn bằng định dạng -V:.

Khi sử dụng đối số -V:, việc chỉ định Công ty sẽ giới hạn lựa chọn trong thời gian chạy từ nhà cung cấp đó, trong khi chỉ định Thẻ sẽ chọn từ tất cả các nhà cung cấp. Lưu ý rằng việc bỏ qua dấu gạch chéo ngụ ý một thẻ:

# Select bất kỳ thời gian chạy được gắn thẻ '3.*' nào
py -V:3

# Select bất kỳ thời gian chạy 'PythonCore' nào được phát hành
py -V:PythonCore/

# Select Thời gian chạy Python 3 mới nhất của PythonCore
py -V:PythonCore/3

Dạng đối số ngắn (-3) chỉ được chọn từ các bản phát hành Python cốt lõi chứ không phải các bản phân phối khác. Tuy nhiên, dạng dài hơn (-V:3) sẽ chọn từ bất kỳ.

Công ty được khớp trên chuỗi đầy đủ, không phân biệt chữ hoa chữ thường. Thẻ được so khớp trên chuỗi đầy đủ hoặc tiền tố, miễn là ký tự tiếp theo là dấu chấm hoặc dấu gạch nối. Điều này cho phép -V:3.1 khớp với 3.1-32, nhưng không khớp với 3.10. Thẻ được sắp xếp theo thứ tự số (3.10 mới hơn 3.1), nhưng được so sánh bằng văn bản (-V:3.01 không khớp với 3.1).

4.12.1.2. Môi trường ảo

Added in version 3.5.

Nếu trình khởi chạy được chạy mà không có thông số kỹ thuật phiên bản Python rõ ràng và môi trường ảo (được tạo bằng mô-đun venv thư viện tiêu chuẩn hoặc công cụ virtualenv bên ngoài) đang hoạt động thì trình khởi chạy sẽ chạy trình thông dịch của môi trường ảo thay vì trình thông dịch chung. Để chạy trình thông dịch chung, hãy tắt môi trường ảo hoặc chỉ định rõ ràng phiên bản Python toàn cầu.

4.12.1.3. Từ một kịch bản

Hãy tạo một tập lệnh Python thử nghiệm - tạo một tệp có tên hello.py với nội dung sau

#! trăn
hệ thống nhập khẩu
sys.stdout.write("xin chào từ Python %s\n" % (sys.version,))

Từ thư mục chứa hello.py, hãy thực thi lệnh:

py xin chào.py

Bạn sẽ thấy số phiên bản của bản cài đặt Python 2.x mới nhất được in. Bây giờ hãy thử thay đổi dòng đầu tiên thành:

#! trăn3

Việc thực hiện lại lệnh bây giờ sẽ in thông tin Python 3.x mới nhất. Giống như các ví dụ dòng lệnh ở trên, bạn có thể chỉ định vòng loại phiên bản rõ ràng hơn. Giả sử bạn đã cài đặt Python 3.7, hãy thử thay đổi dòng đầu tiên thành #! python3.7 và bạn sẽ thấy thông tin phiên bản 3.7 được in ra.

Lưu ý rằng không giống như cách sử dụng tương tác, "python" đơn giản sẽ sử dụng phiên bản Python 2.x mới nhất mà bạn đã cài đặt. Điều này là để tương thích ngược và tương thích với Unix, trong đó lệnh python thường đề cập đến Python 2.

4.12.1.4. Từ các liên kết tập tin

Trình khởi chạy phải được liên kết với các tệp Python (tức là các tệp .py, .pyw, .pyc) khi được cài đặt. Điều này có nghĩa là khi bạn nhấp đúp vào một trong các tệp này từ Windows explorer, trình khởi chạy sẽ được sử dụng và do đó bạn có thể sử dụng các tiện ích tương tự được mô tả ở trên để tập lệnh chỉ định phiên bản sẽ được sử dụng.

Lợi ích chính của việc này là một trình khởi chạy duy nhất có thể hỗ trợ nhiều phiên bản Python cùng lúc tùy thuộc vào nội dung của dòng đầu tiên.

4.12.2. Dòng Shebang

Nếu dòng đầu tiên của tệp tập lệnh bắt đầu bằng #! thì nó được gọi là dòng "shebang". Linux và các hệ điều hành tương tự Unix khác có hỗ trợ riêng cho các dòng như vậy và chúng thường được sử dụng trên các hệ thống như vậy để chỉ ra cách thực thi một tập lệnh. Trình khởi chạy này cho phép sử dụng các tiện ích tương tự với tập lệnh Python trên Windows và các ví dụ trên minh họa việc sử dụng chúng.

Để cho phép các dòng shebang trong tập lệnh Python có thể di chuyển được giữa Unix và Windows, trình khởi chạy này hỗ trợ một số lệnh 'ảo' để chỉ định trình thông dịch nào sẽ sử dụng. Các lệnh ảo được hỗ trợ là:

• /usr/bin/env

• /usr/bin/python

• /usr/local/bin/python

• python

Ví dụ: nếu dòng đầu tiên của tập lệnh của bạn bắt đầu bằng

#! /usr/bin/python

Python mặc định hoặc môi trường ảo đang hoạt động sẽ được định vị và sử dụng. Vì nhiều tập lệnh Python được viết để hoạt động trên Unix sẽ có dòng này, bạn nên thấy rằng trình khởi chạy có thể sử dụng các tập lệnh này mà không cần sửa đổi. Nếu bạn đang viết một tập lệnh mới trên Windows mà bạn hy vọng sẽ hữu ích trên Unix, bạn nên sử dụng một trong các dòng Shebang bắt đầu bằng /usr.

Bất kỳ lệnh ảo nào ở trên đều có thể được gắn với một phiên bản rõ ràng (chỉ là phiên bản chính hoặc phiên bản chính và phụ). Hơn nữa, phiên bản 32 bit có thể được yêu cầu bằng cách thêm "-32" sau phiên bản phụ. tức là /usr/bin/python3.7-32 sẽ yêu cầu sử dụng Python 3.7 32-bit. Nếu môi trường ảo đang hoạt động, phiên bản sẽ bị bỏ qua và môi trường sẽ được sử dụng.

Added in version 3.7: Bắt đầu với python launcher 3.7, có thể yêu cầu phiên bản 64 bit bằng hậu tố "-64". Hơn nữa, có thể chỉ định kiến ​​trúc chính và kiến ​​trúc không phụ (ví dụ: /usr/bin/python3-64).

Thay đổi trong phiên bản 3.11: Hậu tố "-64" không được dùng nữa và hiện ngụ ý "bất kỳ kiến trúc nào không được chứng minh là i386/32-bit". Để yêu cầu một môi trường cụ thể, hãy sử dụng đối số -V:TAG mới với thẻ hoàn chỉnh.

Thay đổi trong phiên bản 3.13: Các lệnh ảo tham chiếu python hiện thích môi trường ảo đang hoạt động hơn là tìm kiếm PATH. Điều này xử lý các trường hợp shebang chỉ định /usr/bin/env python3 nhưng python3.exe không có trong môi trường hoạt động.

Dạng /usr/bin/env của dòng shebang còn có một đặc tính đặc biệt nữa. Trước khi tìm kiếm trình thông dịch Python đã cài đặt, biểu mẫu này sẽ tìm kiếm tệp thực thi PATH để tìm tệp thực thi Python khớp với tên được cung cấp làm đối số đầu tiên. Điều này tương ứng với hành vi của chương trình Unix env, thực hiện tìm kiếm PATH. Nếu không thể tìm thấy tệp thực thi khớp với đối số đầu tiên sau lệnh env nhưng đối số bắt đầu bằng python, thì đối số đó sẽ được xử lý như mô tả cho các lệnh ảo khác. Biến môi trường PYLAUNCHER_NO_SEARCH_PATH có thể được đặt (thành bất kỳ giá trị nào) để bỏ qua tìm kiếm PATH này.

Các dòng Shebang không khớp với bất kỳ mẫu nào trong số này sẽ được tra cứu trong phần [commands] của .INI file của trình khởi chạy. Điều này có thể được sử dụng để xử lý một số lệnh nhất định theo cách phù hợp với hệ thống của bạn. Tên của lệnh phải là một đối số duy nhất (không có khoảng trắng trong tệp thực thi shebang) và giá trị được thay thế là đường dẫn đầy đủ đến tệp thực thi (các đối số bổ sung được chỉ định trong .INI sẽ được trích dẫn như một phần của tên tệp).

[lệnh]
/bin/xpython=C:\Program Files\XPython\python.exe

Bất kỳ lệnh nào không được tìm thấy trong tệp .INI đều được coi là đường dẫn thực thi Windows tuyệt đối hoặc tương đối với thư mục chứa tệp tập lệnh. Đây là sự tiện lợi cho các tập lệnh chỉ dành cho Windows, chẳng hạn như các tập lệnh được tạo bởi trình cài đặt, vì hành vi này không tương thích với các shell kiểu Unix. Các đường dẫn này có thể được trích dẫn và có thể bao gồm nhiều đối số, sau đó đường dẫn đến tập lệnh và mọi đối số bổ sung sẽ được thêm vào.

4.12.3. Đối số trong dòng shebang

Các dòng Shebang cũng có thể chỉ định các tùy chọn bổ sung để chuyển tới trình thông dịch Python. Ví dụ: nếu bạn có một dòng Shebang:

#! /usr/bin/python -v

Sau đó Python sẽ được bắt đầu với tùy chọn -v

4.12.4. Tùy chỉnh

4.12.4.1. Tùy chỉnh thông qua các tập tin INI

Hai tệp .ini sẽ được trình khởi chạy tìm kiếm - py.ini trong thư mục dữ liệu ứng dụng của người dùng hiện tại (%LOCALAPPDATA% hoặc $env:LocalAppData) và py.ini trong cùng thư mục với trình khởi chạy. Các tệp .ini giống nhau được sử dụng cho cả phiên bản 'console' của trình khởi chạy (tức là py.exe) và cho phiên bản 'windows' (tức là pyw.exe).

Tùy chỉnh được chỉ định trong "thư mục ứng dụng" sẽ được ưu tiên hơn tùy chỉnh bên cạnh tệp thực thi, do đó, người dùng, những người có thể không có quyền ghi vào tệp .ini bên cạnh trình khởi chạy, có thể ghi đè các lệnh trong tệp .ini chung đó.

4.12.4.2. Tùy chỉnh các phiên bản Python mặc định

Trong một số trường hợp, vòng loại phiên bản có thể được bao gồm trong lệnh để chỉ ra phiên bản Python nào sẽ được lệnh sử dụng. Bộ hạn định phiên bản bắt đầu bằng số phiên bản chính và có thể tùy ý theo sau bằng dấu chấm ('.') và mã xác định phiên bản phụ. Hơn nữa, có thể chỉ định xem việc triển khai 32 hay 64 bit sẽ được yêu cầu bằng cách thêm "-32" hoặc "-64".

Ví dụ: dòng shebang của #!python không có vòng loại phiên bản, trong khi #!python3 có vòng loại phiên bản chỉ chỉ định một phiên bản chính.

Nếu không tìm thấy bộ định tính phiên bản trong một lệnh, biến môi trường PY_PYTHON có thể được đặt để chỉ định bộ định tính phiên bản mặc định. Nếu nó không được đặt, mặc định là "3". Biến có thể chỉ định bất kỳ giá trị nào có thể được truyền trên dòng lệnh, chẳng hạn như "3", "3.7", "3.7-32" hoặc "3.7-64". (Lưu ý rằng tùy chọn "-64" chỉ khả dụng với trình khởi chạy đi kèm với Python 3.7 hoặc mới hơn.)

Nếu không tìm thấy bộ định tính phiên bản phụ, biến môi trường PY_PYTHON{major} (trong đó {major} là bộ định tính phiên bản chính hiện tại như đã xác định ở trên) có thể được đặt để chỉ định phiên bản đầy đủ. Nếu không tìm thấy tùy chọn nào như vậy, trình khởi chạy sẽ liệt kê các phiên bản Python đã cài đặt và sử dụng bản phát hành nhỏ mới nhất được tìm thấy cho phiên bản chính, có khả năng, mặc dù không được đảm bảo, là phiên bản được cài đặt gần đây nhất trong dòng đó.

Trên Windows 64 bit có cài đặt cả phiên bản 32 bit và 64 bit của cùng một phiên bản Python (major.minor), phiên bản 64 bit sẽ luôn được ưu tiên. Điều này đúng cho cả triển khai trình khởi chạy 32 bit và 64 bit - trình khởi chạy 32 bit sẽ ưu tiên thực hiện cài đặt Python 64 bit của phiên bản được chỉ định nếu có. Điều này là để có thể dự đoán hoạt động của trình khởi chạy chỉ khi biết phiên bản nào được cài đặt trên PC và không quan tâm đến thứ tự chúng được cài đặt (tức là không biết liệu phiên bản 32 hay 64-bit của Python và trình khởi chạy tương ứng đã được cài đặt lần cuối). Như đã lưu ý ở trên, hậu tố "-32" hoặc "-64" tùy chọn có thể được sử dụng trên công cụ xác định phiên bản để thay đổi hành vi này.

Ví dụ:

• Nếu không có tùy chọn liên quan nào được đặt, các lệnh python và python2 sẽ sử dụng phiên bản Python 2.x mới nhất được cài đặt và lệnh python3 sẽ sử dụng Python 3.x mới nhất được cài đặt.

• Lệnh python3.7 sẽ không tham khảo bất kỳ tùy chọn nào vì các phiên bản đã được chỉ định đầy đủ.

• Nếu PY_PYTHON=3, các lệnh python và python3 đều sẽ sử dụng phiên bản Python 3 được cài đặt mới nhất.

• Nếu PY_PYTHON=3.7-32, lệnh python sẽ sử dụng triển khai 32-bit của 3.7 trong khi lệnh python3 sẽ sử dụng Python được cài đặt mới nhất (PY_PYTHON hoàn toàn không được coi là phiên bản chính đã được chỉ định.)

• Nếu PY_PYTHON=3 và PY_PYTHON3=3.7 thì các lệnh python và python3 đều sẽ sử dụng riêng 3.7

Ngoài các biến môi trường, các cài đặt tương tự có thể được định cấu hình trong tệp .INI được trình khởi chạy sử dụng. Phần trong tệp INI được gọi là [defaults] và tên khóa sẽ giống với các biến môi trường mà không có tiền tố PY_ ở đầu (và lưu ý rằng tên khóa trong tệp INI không phân biệt chữ hoa chữ thường.) Nội dung của biến môi trường sẽ ghi đè những thứ được chỉ định trong tệp INI.

Ví dụ:

• Cài đặt PY_PYTHON=3.7 tương đương với file INI chứa:

[mặc định]
trăn=3,7

• Cài đặt PY_PYTHON=3 và PY_PYTHON3=3.7 tương đương với file INI chứa:

[mặc định]
trăn=3
trăn3=3,7

4.12.5. Chẩn đoán

Nếu biến môi trường PYLAUNCHER_DEBUG được đặt (thành bất kỳ giá trị nào), trình khởi chạy sẽ in thông tin chẩn đoán tới stderr (tức là tới bảng điều khiển). Mặc dù thông tin này được quản lý đồng thời dài dòng and, nhưng nó sẽ cho phép bạn xem phiên bản Python nào được tìm thấy, lý do tại sao một phiên bản cụ thể được chọn và dòng lệnh chính xác được sử dụng để thực thi Python mục tiêu. Nó chủ yếu nhằm mục đích thử nghiệm và gỡ lỗi.

4.12.6. Chạy khô

Nếu biến môi trường PYLAUNCHER_DRYRUN được đặt (thành bất kỳ giá trị nào), trình khởi chạy sẽ xuất ra lệnh mà lẽ ra nó sẽ chạy, nhưng sẽ không thực sự khởi chạy Python. Điều này có thể hữu ích cho các công cụ muốn sử dụng trình khởi chạy để phát hiện và sau đó khởi chạy Python trực tiếp. Lưu ý rằng lệnh được ghi vào đầu ra tiêu chuẩn luôn được mã hóa bằng UTF-8 và có thể không hiển thị chính xác trong bảng điều khiển.

4.12.7. Cài đặt theo yêu cầu

Nếu biến môi trường PYLAUNCHER_ALLOW_INSTALL được đặt (thành bất kỳ giá trị nào) và phiên bản Python được yêu cầu chưa được cài đặt nhưng có sẵn trên Microsoft Store thì trình khởi chạy sẽ cố gắng cài đặt phiên bản đó. Điều này có thể yêu cầu sự tương tác của người dùng để hoàn thành và bạn có thể cần phải chạy lại lệnh.

Một biến PYLAUNCHER_ALWAYS_INSTALL bổ sung khiến trình khởi chạy luôn cố gắng cài đặt Python, ngay cả khi nó được phát hiện. Điều này chủ yếu nhằm mục đích thử nghiệm (và nên được sử dụng với PYLAUNCHER_DRYRUN).

4.12.8. Mã trả lại

Các mã thoát sau đây có thể được trình khởi chạy Python trả về. Thật không may, không có cách nào để phân biệt chúng với mã thoát của chính Python.

Tên của các mã được sử dụng trong các nguồn và chỉ mang tính chất tham khảo. Không có cách nào để truy cập hoặc giải quyết chúng ngoài việc đọc trang này. Các mục được liệt kê theo thứ tự bảng chữ cái của tên.

Tên	Giá trị	Mô tả
RC_BAD_VENV_CFG	107	Một pyvenv.cfg đã được tìm thấy nhưng bị hỏng.
RC_CREATE_PROCESS	101	Không khởi chạy được Python.
RC_INSTALLING	111	Quá trình cài đặt đã được bắt đầu nhưng lệnh sẽ cần được chạy lại sau khi hoàn tất.
RC_INTERNAL_ERROR	109	Lỗi không mong muốn. Vui lòng báo cáo lỗi.
RC_NO_COMMANDLINE	108	Không thể lấy dòng lệnh từ hệ điều hành.
RC_NO_PYTHON	103	Không thể tìm thấy phiên bản được yêu cầu.
RC_NO_VENV_CFG	106	Cần có pyvenv.cfg nhưng không tìm thấy.