4. استفاده از پایتون در ویندوز

هدف این سند، ارائه‌ی مروری کلی بر رفتارهای خاص ویندوز است که هنگام استفاده از پایتون در مایکروسافت ویندوز باید از آن‌ها آگاه باشید.

برخلاف اغلب سیستم‌ها و سرویس‌های یونیکس، ویندوز شامل نصب پایتون با پشتیبانی سیستمی نیست. در عوض، می‌توان پایتون را از تعدادی توزیع‌کننده به دست آورد، از جمله مستقیماً از تیم سی‌پایتون. هر توزیع پایتون مزایا و معایب خاص خود را خواهد داشت؛ با این حال، سازگاری با ابزارهای دیگری که استفاده می‌کنید، به‌طور کلی مزیتی ارزشمند است. پیش از پایبند شدن به فرایند شرح‌داده‌شده در اینجا، توصیه می‌کنیم ابزارهای موجود خود را بررسی کنید تا ببینید آیا می‌توانند پایتون را مستقیماً فراهم کنند یا خیر.

برای دریافت پایتون از تیم سی‌پایتون، از Python Install Manager استفاده کنید. این یک ابزار مستقل است که پایتون را به‌صورت فرمان‌های سراسری روی رایانه‌ی ویندوزی شما در دسترس قرار می‌دهد، با سیستم یکپارچه می‌شود و از به‌روزرسانی در طول زمان پشتیبانی می‌کند. می‌توانید Python Install Manager را از python.org/downloads یا از طریق Microsoft Store app دانلود کنید.

پس از نصب Python Install Manager، می‌توانید از دستور سراسری python در هر پایانهی برای راه‌اندازی آخرین نسخه‌ی فعلی پایتون خود استفاده کنید. این نسخه ممکن است به مرور زمان و با افزودن یا حذف نسخه‌های مختلف تغییر کند و دستور py list نشان می‌دهد که کدام نسخه فعلی است.

به‌طور کلی، توصیه می‌کنیم برای هر پروژه یک محیط مجازی ایجاد کنید و برای استفاده از آن، <env>\Scripts\Activate را در پایانه خود اجرا کنید. این کار جداسازی میان پروژه‌ها و سازگاری در طول زمان را فراهم می‌کند و تضمین می‌کند که دستورهای اضافی افزوده‌شده توسط بسته‌ها نیز در نشست شما در دسترس باشند. یک محیط مجازی با استفاده از python -m venv <env path> بسازید.

اگر به نظر می‌رسد دستورات python یا py کار نمی‌کنند، لطفاً به بخش رفع اشکال در ادامه مراجعه کنید. گاهی گام‌های دستی اضافی برای پیکربندی رایانه شما لازم است.

علاوه بر استفاده از مدیر نصب پایتون، پایتون را می‌توان به‌صورت بسته‌های NuGet نیز به دست آورد. برای اطلاعات بیشتر درباره این بسته‌ها، به بسته‌های nuget.org در ادامه مراجعه کنید.

توزیع‌های قابل‌تعبیه، بسته‌های حداقلی پایتون هستند که برای تعبیه در برنامه‌های بزرگ‌تر مناسب‌اند. می‌توان این توزیع‌ها را با استفاده از مدیر نصب پایتون (Python install manager) نصب کرد. برای اطلاعات بیشتر درباره‌ی این بسته‌ها، به بسته‌ی تعبیه‌پذیر در ادامه مراجعه کنید.

4.1. مدیر نصب پایتون

4.1.1. نصب

مدیر نصب پایتون را می‌توان از Microsoft Store app نصب کرد یا از python.org/downloads دانلود و نصب کرد. هر دو نسخه یکسان هستند.

برای نصب از طریق فروشگاه، کافی است روی «نصب» کلیک کنید. پس از اتمام نصب، یک پایانه باز کنید و برای شروع، python را تایپ کنید.

برای نصب پرونده‌ای که از python.org دانلود کرده‌اید، یا دوبار کلیک کنید و «Install» را انتخاب کنید، یا Add-AppxPackage <path to MSIX> را در Windows Powershell اجرا کنید.

پس از نصب، دستورهای python، py و pymanager باید در دسترس باشند. اگر نصب‌های موجودی از پایتون دارید، یا متغیر PATH خود را تغییر داده‌اید، ممکن است لازم باشد آن‌ها را حذف کنید یا تغییرات را واگردانید. برای راهنمایی بیشتر در رفع مشکل دستورهایی که کار نمی‌کنند، به عیب‌یابی مراجعه کنید.

وقتی برای نخستین بار یک ران‌تایم را نصب می‌کنید، به احتمال زیاد از شما خواسته می‌شود که یک پوشه را به PATH خود اضافه کنید. اگر ترجیح می‌دهید از دستور py استفاده کنید، این کار اختیاری است، اما برای کسانی که ترجیح می‌دهند مجموعه کامل نام‌های مستعار (مانند python3.14.exe) در دسترس باشد، ارائه می‌شود. این پوشه به‌طور پیش‌فرض %LocalAppData%\Python\bin خواهد بود، اما ممکن است توسط یک مدیر سیستم سفارشی‌سازی شود. برای افزودن مسیر، روی Start کلیک کنید و عبارت «ویرایش متغیرهای محیطی برای حساب شما» (Edit environment variables for your account) را جست‌وجو کنید تا به صفحه تنظیمات سیستم برسید.

هر ران‌تایم پایتون که نصب می‌کنید، پوشه‌ی مخصوص خود را برای اسکریپت‌ها خواهد داشت. اگر می‌خواهید از آن‌ها استفاده کنید، این پوشه‌ها نیز باید به PATH اضافه شوند.

مدیر نصب پایتون به‌طور خودکار به نسخه‌های جدید به‌روزرسانی می‌شود. این امر بر هیچ‌یک از نصب‌های ران‌تایم‌های پایتون تأثیری نمی‌گذارد. با حذف مدیر نصب پایتون، هیچ‌یک از ران‌تایم‌های پایتون حذف نمی‌شود.

اگر نمی‌توانید MSIX را در شرایط خود نصب کنید (برای مثال، اگر از نرم‌افزار استقرار خودکاری استفاده می‌کنید که از آن پشتیبانی نمی‌کند، یا Windows Server 2019 را هدف قرار می‌دهید)، لطفاً برای اطلاعات بیشتر به نصب پیشرفته در ادامه مراجعه کنید.

4.1.2. کاربرد پایه

دستور توصیه‌شده برای راه‌اندازی پایتون python است که یا نسخه‌ی درخواستی اسکریپت در حال راه‌اندازی، یا یک محیط مجازی فعال، یا نسخه‌ی نصب‌شده‌ی پیش‌فرض را راه‌اندازی می‌کند؛ این نسخه‌ی پیش‌فرض مگر اینکه به‌گونه‌ای دیگر پیکربندی شده باشد، آخرین نسخه‌ی پایدار خواهد بود. اگر هیچ نسخه‌ای به‌طور خاص درخواست نشده باشد و اصلاً هیچ ران‌تایمی نصب نباشد، آخرین نسخه‌ی فعلی به‌طور خودکار نصب خواهد شد.

برای همه سناریوهایی که شامل چندین نسخه‌ی ران‌تایم هستند، فرمان توصیه‌شده py است. می‌توان از این فرمان در هر جایی به‌جای python یا راه‌انداز قدیمی‌تر py.exe استفاده کرد. به‌صورت پیش‌فرض، py همان رفتار python را دارد، اما در عین حال امکان استفاده از گزینه‌های خط فرمان برای انتخاب نسخه‌ی خاص و همچنین زیرفرمان‌هایی برای مدیریت نصب‌ها را نیز فراهم می‌کند. این موارد در ادامه به‌تفصیل شرح داده شده‌اند.

از آنجا که ممکن است فرمان py قبلاً توسط نسخه‌ی قبلی گرفته شده باشد، یک فرمان بدون ابهام pymanager نیز وجود دارد. نصب‌های مبتنی بر اسکریپت که قصد استفاده از مدیر نصب پایتون را دارند، باید به دلیل احتمال کمتر تداخل با نصب‌های موجود، استفاده از pymanager را در نظر بگیرند. تنها تفاوت میان این دو فرمان زمانی است که بدون هیچ آرگومانی اجرا می‌شوند: py مفسر پیش‌فرض شما را راه‌اندازی می‌کند، در حالی که pymanager راهنما را نمایش می‌دهد (pymanager exec ... رفتاری معادل با py ... ارائه می‌دهد).

هر یک از این فرمان‌ها همچنین یک نسخه‌ی پنجره‌ای دارد که از ایجاد پنجره‌ی کنسول اجتناب می‌کند. این نسخه‌ها pyw، pythonw و pywmanager هستند. فرمان python3 نیز گنجانده شده است که فرمان python را تقلید می‌کند. این فرمان برای گرفتن استفاده‌های ناخواسته از فرمان معمول POSIX در ویندوز در نظر گرفته شده است، اما برای استفاده‌ی گسترده یا توصیه در نظر گرفته نشده است.

برای راه‌اندازی ران‌تایم پیش‌فرض خود، python یا py را با آرگومان‌هایی که می‌خواهید به ران‌تایم منتقل شوند (مانند پرونده‌های اسکریپت یا ماژولی که باید راه‌اندازی شود) اجرا کنید:

$> py
...
$> python my-script.py
...
$> py -m this
...

می‌توان ران‌تایم پیش‌فرض را با متغیر محیطی PYTHON_MANAGER_DEFAULT یا یک پرونده پیکربندی بازنویسی کرد. برای اطلاعات درباره‌ی تنظیمات پیکربندی به پیکربندی مراجعه کنید.

برای راه‌اندازی یک ران‌تایم خاص، دستور py گزینه‌ی -V:<TAG> را می‌پذیرد. این گزینه باید پیش از هر گزینه‌ی دیگری مشخص شود. برچسب، بخشی از شناسه‌ی ران‌تایم یا تمام آن است؛ برای ران‌تایم‌های ارائه‌شده از سوی تیم سی‌پایتون، این برچسب شبیه نسخه است که ممکن است همراه با پلتفرم باشد. برای سازگاری، در مواردی که برچسب به یک نسخه‌ی رسمی اشاره دارد و با 3 آغاز می‌شود، می‌توان V: را حذف کرد.

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

ممکن است ران‌تایم‌های توزیع‌کنندگان دیگر به گنجاندن شرکت نیز نیاز داشته باشند. شرکت باید با یک اسلش (چه / و چه \) از برچسب جدا شود و ممکن است به هر پیشوندی از مقدار کامل خود کوتاه شود. هنگامی که شرکت PythonCore باشد، مشخص کردن آن اختیاری است، و هنگامی که آخرین نسخه از یک شرکت مشخص را می‌خواهید، مشخص کردن برچسب اختیاری است (اما نه اسلش).

$> py -V:Distributor\1.0 ...
$> py -V:distrib/ ...

اگر نسخه‌ای مشخص نشده باشد، اما پرونده اسکریپتی داده شود، اسکریپت از نظر وجود سطر خط مفسر بررسی خواهد شد. این یک قالب خاص برای سطر نخست در یک پرونده است که امکان بازنویسی دستور را فراهم می‌کند. برای اطلاعات بیشتر به سطرهای مفسر مراجعه کنید. وقتی خط مفسر وجود نداشته باشد یا نتوان آن را حل کرد، اسکریپت با ران‌تایم پیش‌فرض اجرا خواهد شد.

اگر در یک محیط مجازی فعال در حال اجرا باشید، نسخه‌ی خاصی را درخواست نکرده باشید و سطر خط مفسر وجود نداشته باشد، ران‌تایم پیش‌فرض همان محیط مجازی خواهد بود. در این سناریو، احتمالاً دستور python از قبل بازنویسی شده و هیچ‌یک از این بررسی‌ها انجام نشده‌اند. با این حال، این رفتار تضمین می‌کند که بتوان از دستور py به‌صورت قابل تعویض استفاده کرد.

وقتی هیچ ران‌تایمی نصب نشده باشد، هر دستور اجرا تلاش می‌کند نسخه‌ی درخواستی را نصب کرده و آن را اجرا کند. اما پس از اینکه نسخه‌ای نصب شود، تنها دستورهای py exec ... و pymanager exec ... در صورت نبود نسخه‌ی درخواستی، آن را نصب می‌کنند. سایر اشکال دستورها خطایی نمایش می‌دهند و شما را هدایت می‌کنند که ابتدا از py install استفاده کنید.

4.1.3. راهنمای دستور

فرمان py help فهرست کامل فرمان‌های پشتیبانی‌شده را همراه با گزینه‌های آن‌ها نمایش می‌دهد. به هر فرمانی می‌توان گزینه‌ی -? را برای نمایش راهنمای آن پاس داد، یا نام آن را به py help پاس داد.

$> py help
$> py help install
$> py install /?

همه‌ی دستورها از برخی گزینه‌های مشترک پشتیبانی می‌کنند که با py help نمایش داده می‌شوند. این گزینه‌ها باید پس از هر زیر‌دستوری مشخص شوند. مشخص کردن -v یا --verbose میزان خروجی نمایش‌داده‌شده را افزایش می‌دهد و -vv آن را برای مقاصد اشکال‌زدایی بیشتر افزایش می‌دهد. ارسال -q یا --quiet خروجی را کاهش می‌دهد و -qq آن را بیشتر کاهش می‌دهد.

گزینه‌ی --config=<PATH> به شما امکان می‌دهد یک پرونده‌ی پیکربندی را برای نادیده گرفتن چندین تنظیم به‌صورت همزمان مشخص کنید. برای اطلاعات بیشتر درباره‌ی این پرونده‌ها، به پیکربندی در ادامه مراجعه کنید.

4.1.4. فهرست کردن ران‌تایم‌ها

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

فهرست ران‌تایم‌های نصب‌شده را می‌توان با استفاده از py list مشاهده کرد. می‌توان یک پالایه به شکل یک یا چند برچسب (با یا بدون مشخص‌کننده شرکت) افزود و هر یک می‌تواند برای محدود کردن به یک بازه، شامل پیشوند <، <=، >= یا > باشد.

طیفی از قالب‌ها پشتیبانی می‌شوند و می‌توان آن‌ها را به‌عنوان گزینه‌ی --format=<FMT> یا -f <FMT> ارسال کرد. قالب‌ها شامل table (نمای جدولی کاربرپسند)، csv (جدول جداشده با کاما)، json (یک بلاب JSON واحد)، jsonl (یک بلاب JSON برای هر نتیجه)، exe (فقط مسیر پرونده اجرایی) و prefix (فقط مسیر پیشوند) هستند.

گزینه‌ی --one یا -1 تنها یک نتیجه را نمایش می‌دهد. اگر ران‌تایم پیش‌فرض در میان نتایج باشد، همان است که نمایش داده می‌شود. در غیر این صورت، «بهترین» نتیجه نمایش داده می‌شود («بهترین» عمداً به‌طور مبهم تعریف شده است، اما معمولاً جدیدترین نسخه خواهد بود). نتیجه‌ای که py list --one <TAG> نمایش می‌دهد با ران‌تایمی که py -V:<TAG> راه‌اندازی می‌کند مطابقت دارد.

گزینه‌ی --only-managed نتایجی را که توسط مدیر نصب پایتون نصب‌نشده‌اند مستثنا می‌کند. این ویژگی برای تعیین اینکه کدام ران‌تایم‌ها را می‌توان از طریق دستور py به‌روزرسانی یا حذف کرد، مفید است.

گزینه‌ی --online شکل کوتاهی از دادن --source=<URL> همراه با منبع پیش‌فرض است. با دادن هر یک از این گزینه‌ها، فهرست آنلاین برای ران‌تایم‌های قابل نصب جستجو می‌شود. نتیجه‌ای که py list --online --one <TAG> نمایش می‌دهد، با ران‌تایمی که py install <TAG> نصب می‌کند مطابقت خواهد داشت.

$> py list --online 3.14

برای سازگاری با راه‌انداز قدیمی، فرمان‌های --list، --list-paths، -0 و -0p (مثلاً py -0p) حفظ شده‌اند. این فرمان‌ها گزینه‌های اضافی را نمی‌پذیرند و خروجی با قالب قدیمی تولید خواهند کرد.

4.1.5. نصب ران‌تایم‌ها

$> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]

می‌توان نسخه‌های جدید ران‌تایم را با استفاده از py install افزود. می‌توان یک یا چند برچسب را مشخص کرد و از برچسب ویژه‌ی default برای انتخاب نسخه‌ی پیش‌فرض استفاده کرد. محدوده‌ها برای نصب پشتیبانی نمی‌شوند.

گزینه‌ی --source=<URL> اجازه می‌دهد تا نمایه‌ی آنلاینی که برای دریافت ران‌تایم‌ها استفاده می‌شود، بازنویسی شود. این گزینه می‌تواند همراه با یک نمایه‌ی آفلاین استفاده شود، همان‌طور که در نصب‌های آفلاین نشان داده شده است.

با ارسال --force، پرونده‌های ذخیره‌شده در نهانگاه نادیده گرفته می‌شوند و هر نصب موجود حذف می‌شود تا با نصب مشخص‌شده جایگزین شود.

با ارسال --update، در صورتی که نسخه جدید جدیدتر باشد، نصب‌های موجود جایگزین می‌شوند. در غیر این صورت، دست‌نخورده باقی می‌مانند. اگر هیچ برچسبی همراه --update ارائه نشود، تمام نصب‌های مدیریت‌شده توسط مدیر نصب پایتون، در صورت وجود نسخه‌های جدیدتر، به‌روزرسانی می‌شوند. به‌روزرسانی‌ها هرگونه تغییرات اعمال‌شده روی نصب، از جمله بسته‌های نصب‌شده به صورت سراسری، را حذف می‌کنند، اما محیط‌های مجازی به کار خود ادامه خواهند داد.

با ارسال --dry-run، خروجی و گزارش‌ها تولید می‌شوند، اما هیچ نصبی تغییر نمی‌کند.

ارسال --refresh تمام ثبت‌های مربوط به ران‌تایم‌های نصب‌شده را به‌روزرسانی می‌کند. این کار میان‌برهای منوی Start، کلیدهای رجیستری و نام‌های مستعار سراسری (مانند python3.14.exe یا برای هر یک از اسکریپت‌های نصب‌شده) را بازایجاد می‌کند. این موارد هنگام نصب هر ران‌تایم به‌صورت خودکار بازآوری می‌شوند، اما ممکن است پس از نصب بسته‌ها نیاز به بازآوری دستی داشته باشند.

علاوه بر گزینه‌های بالا، گزینه‌ی --target به‌جای انجام یک نصب معمولی، ران‌تایم را در پوشه‌ی مشخص‌شده استخراج می‌کند. این کار برای تعبیه ران‌تایم‌ها در برنامه‌های بزرگ‌تر مفید است. برخلاف نصب معمولی، py از ران‌تایم استخراج‌شده آگاه نخواهد بود و هیچ میان‌بری در منوی Start یا میان‌بر دیگری ایجاد نخواهد شد. برای راه‌اندازی ران‌تایم، پرونده اجرایی اصلی (معمولاً python.exe) را که در پوشه‌ی هدف قرار دارد، مستقیماً اجرا کنید.

$> py install ... [-t=|--target=<PATH>] <TAG>

دستور py exec ران‌تایم درخواستی را در صورتی که از قبل موجود نباشد نصب می‌کند. این کار توسط پیکربندی automatic_install (PYTHON_MANAGER_AUTOMATIC_INSTALL) کنترل می‌شود و به‌صورت پیش‌فرض فعال است. اگر اصلاً هیچ ران‌تایمی در دسترس نباشد، همه‌ی دستورهای اجرا در صورت مجاز بودنِ تنظیم پیکربندی، نصب خودکار انجام می‌دهند. این برای تضمین تجربه‌ی خوب برای کاربران جدید است، اما به‌طور کلی نباید به‌جای استفاده از دستور py exec یا دستورهای نصب صریح به آن تکیه کرد.

4.1.6. نصب‌های آفلاین

برای انجام نصب‌های آفلاین پایتون، ابتدا باید یک اندیس آفلاین روی ماشینی که به شبکه دسترسی دارد ایجاد کنید.

$> py install --download=<PATH> ... <TAG>...

گزینه‌ی --download=<PATH> بسته‌های مربوط به برچسب‌های فهرست‌شده را دانلود می‌کند و پوشه‌ای حاوی آن‌ها و یک پرونده‌ی index.json مناسب برای نصب بعدی ایجاد می‌کند. می‌توانید تمام این پوشه را به رایانه‌ی آفلاین منتقل کنید و از آن برای نصب یک یا چند مورد از ران‌تایم‌های همراه استفاده کنید:

$> py install --source="<PATH>\index.json" <TAG>...

مدیر نصب پایتون را می‌توان با دانلود کردن نصب‌کننده‌ی آن و انتقال آن به رایانه‌ی دیگری پیش از نصب، نصب کرد.

از طرف دیگر، می‌توان پرونده‌های ZIP موجود در یک پوشه اندیس آفلاین را به‌سادگی به رایانه دیگری منتقل و در آنجا استخراج کرد. این کار نصب را به هیچ شکلی ثبت نمی‌کند و در نتیجه باید آن را با ارجاع مستقیم به پرونده‌های اجرایی موجود در پوشه استخراج‌شده اجرا کرد، اما در مواردی که نصب مدیر نصب پایتون (Python install manager) ممکن یا مناسب نیست، گاهی این رویکرد مطلوب‌تری است.

به این ترتیب، می‌توان ران‌تایم‌های پایتون را روی ماشینی که به اینترنت دسترسی ندارد نصب و مدیریت کرد.

4.1.7. لغو نصب ران‌تایم‌ها

$> py uninstall [-y|--yes] <TAG>...

ران‌تایم‌ها را می‌توان با استفاده از دستور py uninstall حذف کرد. باید یک یا چند برچسب مشخص شود. بازه‌ها در اینجا پشتیبانی نمی‌شوند.

گزینه‌ی --yes پیش از حذف نصب، اعلان تأیید را دور می‌زند.

به‌جای ارسال تگ‌ها به‌صورت جداگانه، می‌توان گزینه‌ی --purge را مشخص کرد. با این کار، تمام ران‌تایم‌های مدیریت‌شده توسط مدیر نصب پایتون حذف می‌شوند و پاک‌سازی منوی Start، رجیستری و تمام نهانگاه‌های دانلود نیز انجام می‌شود. ران‌تایم‌هایی که توسط مدیر نصب پایتون نصب نشده‌اند تحت تأثیر قرار نمی‌گیرند و پرونده‌های پیکربندی ایجادشده به‌صورت دستی نیز تحت تأثیر قرار نمی‌گیرند.

$> py uninstall [-y|--yes] --purge

مدیر نصب پایتون را می‌توان از طریق صفحه‌ی تنظیمات «برنامه‌های نصب‌شده» ویندوز حذف کرد. این کار هیچ ران‌تایمی را حذف نمی‌کند و آن‌ها همچنان قابل استفاده خواهند بود، هرچند دستورهای سراسری python و py حذف خواهند شد. با نصب مجدد مدیر نصب پایتون می‌توانید دوباره این ران‌تایم‌ها را مدیریت کنید. برای پاک‌سازی کامل تمام ران‌تایم‌های پایتون، پیش از حذف مدیر نصب پایتون، آن را با --purge اجرا کنید.

4.1.8. پیکربندی

مدیر نصب پایتون با یک سلسله‌مراتب از پرونده‌های پیکربندی، متغیرهای محیطی، گزینه‌های خط فرمان و تنظیمات رجیستری پیکربندی می‌شود. به‌طور کلی، پرونده‌های پیکربندی قادر به پیکربندی همه‌چیز هستند، از جمله مکان سایر پرونده‌های پیکربندی، در حالی که تنظیمات رجیستری فقط مخصوص مدیر سیستم هستند و پرونده‌های پیکربندی را نادیده می‌گیرند. گزینه‌های خط فرمان همه تنظیمات دیگر را نادیده می‌گیرند، اما همه گزینه‌ها در دسترس نیستند.

این بخش پیش‌فرض‌ها را توصیف می‌کند، اما آگاه باشید که ممکن است نصب‌های تغییر داده‌شده یا بازنویسی‌شده، تنظیمات را به شکل متفاوتی حل کنند.

ممکن است یک پرونده پیکربندی سراسری توسط مدیر سیستم پیکربندی شود و ابتدا خوانده می‌شود. پرونده پیکربندی کاربر در %AppData%\Python\pymanager.json ذخیره می‌شود (توجه داشته باشید که این مکان زیر Roaming است، نه Local) و در مرحله بعد خوانده می‌شود و هر تنظیمی از پرونده‌های قبلی را بازنویسی می‌کند. می‌توان یک پرونده پیکربندی اضافی را از طریق متغیر محیطی PYTHON_MANAGER_CONFIG یا گزینه خط فرمان --config مشخص کرد (اما نه هر دو). این مکان‌ها ممکن است توسط گزینه‌های سفارشی‌سازی مدیریتی که در ادامه فهرست شده‌اند تغییر یابند.

تنظیمات زیر، تنظیماتی هستند که به‌احتمال زیاد در استفاده‌ی عادی تغییر داده می‌شوند. بخش‌های بعدی تنظیماتی را فهرست می‌کنند که برای سفارشی‌سازی مدیریتی در نظر گرفته شده‌اند.

گزینه‌های پیکربندی استاندارد

کلید پیکربندی	متغیر محیطی	توضیحات
default_tag	PYTHON_MANAGER_DEFAULT	نسخه‌ی پیش‌فرض ترجیحی برای اجرا یا نصب. به‌طور پیش‌فرض، این نسخه به‌عنوان جدیدترین نسخه‌ی غیرپیش‌انتشار از تیم سی‌پایتون تفسیر می‌شود.
default_platform	PYTHON_MANAGER_DEFAULT_PLATFORM	پلتفرم پیش‌فرض ترجیحی برای راه‌اندازی یا نصب. این به‌عنوان پسوندی برای برچسب مشخص‌شده در نظر گرفته می‌شود، به‌طوری که py -V:3.14 در صورت وجود، نصبِ 3.14-64 را ترجیح می‌دهد (و default_platform برابر با -64 باشد)، اما اگر هیچ نصب برچسب‌داری وجود نداشته باشد، از 3.14 استفاده خواهد کرد.
logs_dir	PYTHON_MANAGER_LOGS	محلی که پرونده‌های گزارش در آن نوشته می‌شوند. به‌طور پیش‌فرض، %TEMP%.
automatic_install	PYTHON_MANAGER_AUTOMATIC_INSTALL	برای اجازه دادن به نصب خودکار هنگام استفاده از py exec برای راه‌اندازی (یا py وقتی هنوز هیچ ران‌تایمی نصب نشده است)، مقدار True را قرار دهید. سایر دستورات، صرف‌نظر از این تنظیم، به‌طور خودکار نصب انجام نمی‌دهند. به‌طور پیش‌فرض، true است.
include_unmanaged	PYTHON_MANAGER_INCLUDE_UNMANAGED	True برای اجازه دادن به فهرست‌کردن و راه‌اندازی ران‌تایم‌هایی که توسط مدیر نصب پایتون نصب نشده‌اند، یا false برای مستثنی کردن آن‌ها. به‌طور پیش‌فرض، true.
shebang_can_run_anything	PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING	درست برای اجازه دادن به سطرهای مفسر در پرونده‌های .py تا برنامه‌هایی غیر از ران‌تایم‌های پایتون را راه‌اندازی کنند، یا نادرست برای جلوگیری از آن. به‌طور پیش‌فرض، درست است.
shebang_templates	(هیچ)	نگاشت از قالب سطر shebang به فرمان جایگزین، مانند py -V:<tag> یا یک رشته جانشین. برای جزئیات بیشتر به سطرهای مفسر مراجعه کنید.
log_level	PYMANAGER_VERBOSE, PYMANAGER_DEBUG	سطح پیش‌فرض خروجی را تنظیم می‌کند (۰ تا ۵۰). مقدار پیش‌فرض ۲۰ است. مقادیر پایین‌تر خروجی بیشتری تولید می‌کنند. متغیرهای محیطی بولی هستند و ممکن است هنگام راه‌اندازی خروجی اضافی تولید کنند که بعداً توسط پیکربندی‌های دیگر سرکوب می‌شود.
confirm	PYTHON_MANAGER_CONFIRM	True برای تأیید برخی کنش‌ها پیش از انجام آن‌ها (مانند uninstall)، یا false برای نادیده گرفتن تأیید. به‌طور پیش‌فرض، true است.
install.source	PYTHON_MANAGER_SOURCE_URL	فید ایندکس را نادیده بگیرید تا نصب‌های جدید را از آن به دست آورید.
install.enable_entrypoints	(هیچ)	اگر True باشد، دستورات سراسری برای بسته‌های نصب‌شده (مانند pip.exe) تولید می‌شوند. این دستورات توسط خود بسته‌ها تعریف می‌شوند. اگر روی false تنظیم شود، تنها برای مفسر پایتون دستورات سراسری ایجاد می‌شود. به‌طور پیش‌فرض، true است. پس از تغییر این تنظیم، باید py install --refresh را اجرا کنید.
list.format	PYTHON_MANAGER_LIST_FORMAT	قالب پیش‌فرض استفاده‌شده توسط فرمان py list را مشخص می‌کند. به‌صورت پیش‌فرض، table است.
install_dir	(هیچ)	پوشه ریشه‌ای را مشخص کنید که ران‌تایم‌ها در آن نصب خواهند شد. اگر این تنظیم را تغییر دهید، ران‌تایم‌های پیش‌تر نصب‌شده قابل استفاده نخواهند بود، مگر آن‌که آن‌ها را به مکان جدید منتقل کنید.
global_dir	(هیچ)	پوشه‌ای را مشخص کنید که دستورات سراسری (مانند python3.14.exe و pip.exe) در آن ذخیره می‌شوند. این پوشه باید به PATH شما اضافه شود تا دستورات از طریق پایانه شما در دسترس باشند.
download_dir	(هیچ)	پوشه‌ای را مشخص کنید که پرونده‌های دانلودشده در آن ذخیره می‌شوند. این پوشه یک نهانگاه موقت است و می‌توان آن را هر از گاهی پاک‌سازی کرد.

نام‌های نقطه‌دار باید درون اشیاء JSON تودرتو شوند؛ برای مثال، list.format به‌صورت {"list": {"format": "table"}} مشخص می‌شود.

4.1.9. سطرهای مفسر

اگر سطر اول یک پرونده اسکریپت با #! آغاز شود، به‌عنوان سطر «خط مفسر» شناخته می‌شود. لینوکس و دیگر سیستم‌عامل‌های شبه‌یونیکس به‌صورت بومی از چنین سطرهایی پشتیبانی می‌کنند و در چنین سیستم‌هایی به‌طور رایج برای مشخص کردن اینکه یک اسکریپت چگونه باید اجرا شود استفاده می‌شوند. دستورهای python و py اجازه می‌دهند همین امکانات با اسکریپت‌های پایتون در ویندوز استفاده شوند.

برای اینکه سطرهای مفسر در اسکریپت‌های پایتون بین یونیکس و ویندوز قابل حمل باشند، تعدادی فرمان «مجازی» برای مشخص کردن اینکه از کدام مفسر استفاده شود، پشتیبانی می‌شوند. فرمان‌های مجازی پشتیبانی‌شده عبارت‌اند از:

• /usr/bin/env <ALIAS>

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

• /usr/bin/<ALIAS>

• /usr/local/bin/<ALIAS>

• <ALIAS>

برای مثال، اگر سطر اول اسکریپت شما شروع شود با

#! /usr/bin/python

پایتون پیش‌فرض یا یک محیط مجازی فعال یافته و مورد استفاده قرار می‌گیرد. از آنجا که بسیاری از اسکریپت‌های پایتون که برای کار روی یونیکس نوشته شده‌اند، از قبل این سطر را دارند، خواهید دید که این اسکریپت‌ها بدون تغییر توسط راه‌انداز قابل استفاده هستند. اگر در ویندوز اسکریپت جدیدی می‌نویسید که امیدوارید روی یونیکس مفید باشد، باید از یکی از سطرهای خط مفسر که با /usr شروع می‌شوند استفاده کنید.

در هر یک از دستورهای مجازی بالا می‌توان <ALIAS> را با نام مستعاری از یک ران‌تایم نصب‌شده جایگزین کرد. به عبارت دیگر، هر دستوری که در پوشه سراسری نام‌های مستعار تولید‌شده باشد (پوشه‌ای که ممکن است آن را به متغیر محیطی PATH خود اضافه کرده باشید) را می‌توان در یک خط مفسر به‌کار برد، حتی اگر روی PATH شما نباشد. این امر امکان استفاده از سطرهای مفسری مانند /usr/bin/python3.12 برای انتخاب یک ران‌تایم خاص را فراهم می‌کند.

اگر هیچ ران‌تایمی نصب نشده باشد، یا اگر نصب خودکار فعال باشد، ران‌تایم درخواستی در صورت نیاز نصب خواهد شد. برای اطلاعات درباره‌ی تنظیمات پیکربندی به پیکربندی مراجعه کنید.

شکل /usr/bin/env سطر خط مفسر همچنین متغیر محیطی PATH را برای فرمان‌های شناسایی‌نشده جست‌وجو می‌کند. این رفتار با رفتار برنامه‌ی env یونیکس مطابقت دارد که همان جست‌وجو را انجام می‌دهد، اما ترجیح می‌دهد فرمان‌های شناخته‌شده‌ی پایتون را اجرا کند. هنگام جست‌وجو برای پرونده‌های اجرایی دلخواه، ممکن است هشداری نمایش داده شود، و این جست‌وجو را می‌توان با گزینه‌ی پیکربندی shebang_can_run_anything غیرفعال کرد.

سطرهای مفسر که با هیچ‌یک از الگوها مطابقت نداشته باشند، به‌عنوان مسیرهای اجرایی ویندوز در نظر گرفته می‌شوند که مطلق‌اند یا نسبت به پوشه‌ی حاوی پرونده‌ی اسکریپت نسبی‌اند. این یک سودمندی برای اسکریپت‌های مخصوص ویندوز است، مانند اسکریپت‌هایی که توسط یک نصاب تولید می‌شوند، زیرا این رفتار با پوسته‌های سبک یونیکس سازگار نیست. این مسیرها می‌توانند داخل علامت نقل‌قول قرار بگیرند و می‌توانند شامل چندین آرگومان باشند؛ پس از آن‌ها، مسیر اسکریپت و هر آرگومان اضافی دیگری به آن‌ها الحاق خواهد شد. این قابلیت را می‌توان با گزینه‌ی پیکربندی shebang_can_run_anything غیرفعال کرد.

از نسخه 26.3 مدیر نصب پایتون به بعد، می‌توانید قالب‌های سفارشی خط مفسر را به پرونده پیکربندی خود اضافه کنید. شیء shebang_templates را با یک عضو برای هر قالب (رشته‌ای که باید تطبیق داده شود) و فرمانی که هنگام تطبیق قالب استفاده می‌شود، اضافه کنید. بیشتر فرمان‌ها باید py -V:<tag> (یا pyw) باشند تا یکی از ران‌تایم‌های نصب‌شده‌ی شما اجرا شود. شکل py -3.<version> نیز مجاز است، همان‌طور که py ساده برای اجرای پیش‌فرض نیز مجاز است. هیچ آرگومان دیگری پشتیبانی نمی‌شود.

{
    "shebang_templates": {
        "/usr/bin/python": "py",
        "/usr/bin/my_custom_python": "py -V:MyCustomPython/3"
    }
}

اگر فرمان جایگزین py یا pyw نباشد، در خط مفسر بازنویسی می‌شود و پردازش عادی ادامه می‌یابد. اگر اجرای پرونده‌های اجرایی دلخواه مجاز باشد، با مشخص کردن مسیر کامل می‌توانید از پایتون به هر پرونده اجرایی تغییر مسیر دهید. الگو باید یا تمام سطر را (با نادیده گرفتن فاصله‌های ابتدایی و انتهایی) تطبیق دهد، یا تا اولین فاصله در خط مفسر.

توجه

رفتار سطرهای مفسر در مدیر نصب پایتون تفاوت‌های ظریفی با راه‌انداز قبلی py.exe دارد و گزینه‌های پیکربندی قدیمی دیگر اعمال نمی‌شوند. اگر به‌طور خاص به رفتار یا پیکربندی قدیمی وابسته‌اید، توصیه می‌کنیم legacy launcher را نصب کنید. دستور py راه‌انداز قدیمی به‌طور پیش‌فرض بر دستور PyManager غلبه خواهد کرد و برای نصب و لغو نصب، باید از دستورهای pymanager استفاده کنید.

4.1.10. نصب پیشرفته

در موقعیت‌هایی که نمی‌توان MSIX را نصب کرد، مانند برخی از پلتفرم‌های توزیع مدیریتی قدیمی‌تر، یک MSI از طریق صفحه‌ی دانلود python.org در دسترس است. این MSI رابط کاربری ندارد و تنها می‌تواند نصب در سطح ماشین (per-machine) را در مکان پیش‌فرض خود در Program Files انجام دهد. این MSI تلاش می‌کند متغیر محیطی PATH سیستم را طوری تغییر دهد که این مکان نصب را در بر بگیرد، اما حتماً این مورد را در پیکربندی خودتان اعتبارسنجی کنید.

توجه

ویندوز سرور ۲۰۱۹ تنها نسخه‌ی ویندوز مورد پشتیبانی سی‌پایتون است که از MSIX پشتیبانی نمی‌کند. برای ویندوز سرور ۲۰۱۹، باید از MSI استفاده کنید.

آگاه باشید که بسته‌ی MSI هیچ ران‌تایمی را همراه ندارد و از این رو بدون ایجاد یک اندیس نصب آفلاین، برای نصب در محیط‌های آفلاین مناسب نیست. برای کسب اطلاعات درباره‌ی مدیریت این سناریوها به نصب‌های آفلاین و پیکربندی مدیریتی مراجعه کنید.

ران‌تایم‌های نصب‌شده توسط MSI با ران‌تایم‌های نصب‌شده توسط MSIX مشترک‌اند و همگی فقط در سطح کاربر هستند. مدیر نصب پایتون از نصب ران‌تایم‌ها در سطح ماشین پشتیبانی نمی‌کند. برای شبیه‌سازی نصب در سطح ماشین، می‌توانید از py install --target=<shared location> با دسترسی مدیر استفاده کنید و تغییرات سراسری سیستم خود را به PATH، رجیستری یا منوی Start اضافه کنید.

هنگامی که MSIX نصب شده باشد، اما دستورات در متغیر محیطی PATH در دسترس نباشند، می‌توان آن‌ها را در %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km یا %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0 یافت؛ بسته به اینکه از python.org یا از طریق Windows Store نصب شده باشد. تلاش برای اجرای مستقیم پرونده اجرایی از Program Files توصیه نمی‌شود.

برای نصب مدیر نصب پایتون به‌صورت برنامه‌ای، ساده‌ترین راه استفاده از WinGet است که همراه با تمام نسخه‌های پشتیبانی‌شده‌ی ویندوز ارائه می‌شود:

$> winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity

# Optionally run the configuration checker and accept all changes
$> py install --configure -y

برای دانلود مدیر نصب پایتون و نصب آن روی رایانه‌ی دیگری، دستور WinGet زیر پرونده‌های مورد نیاز را از فروشگاه به پوشه‌ی Downloads شما دانلود می‌کند (برای سفارشی‌کردن مکان خروجی، -d <location> را اضافه کنید). این دستور همچنین یک پرونده‌ی YAML تولید می‌کند که به نظر غیرضروری می‌رسد، زیرا MSIX دانلود‌شده را می‌توان با راه‌اندازی آن یا با استفاده از دستورهای زیر نصب کرد.

$> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --accept-source-agreements

برای نصب یا حذف یک MSIX به‌صورت برنامه‌ای و تنها با استفاده از PowerShell، توصیه می‌شود از cmdlet‌های PowerShell با نام‌های Add-AppxPackage و Remove-AppxPackage استفاده کنید:

$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
...
$> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage

ویندوز می‌تواند آخرین نسخه را با پاس دادن پرونده AppInstaller به دستور Add-AppxPackage دانلود و نصب کند. این روش با استفاده از MSIX موجود در python.org نصب را انجام می‌دهد و فقط برای مواردی توصیه می‌شود که نصب از طریق Store (به‌صورت تعاملی یا با استفاده از WinGet) ممکن نباشد.

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

ممکن است از ابزارها و API‌های دیگری نیز برای فراهم‌سازی (provision) یک بسته‌ی MSIX برای همه کاربران یک رایانه استفاده شود، اما پایتون این مورد را یک سناریوی پشتیبانی‌شده تلقی نمی‌کند. پیشنهاد می‌کنیم کامندلت (cmdlet) Add-AppxProvisionedPackage در PowerShell، کلاس بومی PackageManager ویندوز، یا مستندات و پشتیبانی ابزار استقرار خود را بررسی کنید.

صرف‌نظر از روش نصب، کاربران همچنان باید نسخه‌های خودشان از خودِ پایتون را نصب کنند، زیرا بدون ورود کاربر به سیستم، هیچ راهی برای راه‌اندازی آن نصب‌ها وجود ندارد. هنگام استفاده از MSIX، آخرین نسخه پایتون بدون نیاز به دسترسی به شبکه برای نصب در دسترس همه کاربران خواهد بود.

توجه داشته باشید که بسته‌های MSIX قابل دانلود از فروشگاه (Store) و از وب‌سایت پایتون تفاوت‌های ظریفی دارند و نمی‌توان آن‌ها را هم‌زمان نصب کرد. هر جا که ممکن است، پیشنهاد می‌کنیم از دستورهای WinGet بالا برای دانلود بسته از فروشگاه استفاده کنید تا خطر ایجاد نصب‌های متعارض کاهش یابد. هیچ‌گونه محدودیت مجوزدهی برای مدیر نصب پایتون وجود ندارد که مانع استفاده از بسته‌ی فروشگاه به این شکل شود.

4.1.11. پیکربندی مدیریتی

تعدادی گزینه وجود دارد که ممکن است برای مدیران در بازنویسی پیکربندی مدیر نصب پایتون سودمند باشد. از این گزینه‌ها می‌توان برای فراهم کردن نهانگاه‌گذاری محلی، غیرفعال کردن انواع خاصی از میان‌برها و بازنویسی محتوای همراه استفاده کرد. تمام گزینه‌های پیکربندی بالا، و همچنین گزینه‌های زیر، قابل تنظیم هستند.

گزینه‌های پیکربندی را می‌توان در رجیستری با تنظیم مقادیر زیر HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager بازنویسی کرد، که در آن نام مقدار با کلید پیکربندی مطابقت دارد و نوع مقدار REG_SZ است. توجه داشته باشید که خودِ این کلید نیز قابل سفارشی‌سازی است، اما تنها با تغییر پرونده پیکربندی اصلی که همراه مدیر نصب پایتون توزیع می‌شود. با این حال، توصیه می‌کنیم که مقادیر رجیستری تنها برای تنظیم base_config به یک پرونده JSON حاوی مجموعه کامل بازنویسی‌ها استفاده شوند. بازنویسی‌های کلید رجیستری هر تنظیم پیکربندی‌شده دیگری را جایگزین خواهند کرد، در حالی که base_config به کاربران اجازه می‌دهد تنظیماتی را که ممکن است به آن‌ها نیاز داشته باشند، بیشتر تغییر دهند.

توجه داشته باشید که بیشتر تنظیماتی که متغیرهای محیطی دارند، از آن متغیرها پشتیبانی می‌کنند، زیرا تنظیم پیش‌فرض آن‌ها همان متغیر را مشخص می‌کند. اگر آن‌ها را بازنویسی کنید، آن متغیر محیطی دیگر کار نخواهد کرد، مگر آن‌که آن را با متغیر محیطی دیگری بازنویسی کنید. برای مثال، مقدار پیش‌فرض confirm به‌طور لفظی %PYTHON_MANAGER_CONFIRM% است که متغیر را در زمان بارگذاری حل می‌کند. اگر مقدار را به yes بازنویسی کنید، دیگر از آن متغیر محیطی استفاده نخواهد شد. اگر مقدار را به %CONFIRM% بازنویسی کنید، به‌جای آن از این متغیر محیطی استفاده خواهد شد.

تنظیمات پیکربندی که مسیر هستند، به‌صورت نسبی نسبت به پوشه‌ای تفسیر می‌شوند که پرونده‌ی پیکربندیِ مشخص‌کننده‌ی آن‌ها را در بر دارد.

گزینه‌های پیکربندی مدیریتی

کلید پیکربندی	توضیحات
base_config	پرونده پیکربندی با بالاترین اولویت برای خواندن. توجه داشته باشید که تنها پرونده پیکربندی توکار و رجیستری می‌توانند این تنظیم را تغییر دهند.
user_config	دومین پرونده پیکربندی برای خواندن.
additional_config	سومین پرونده پیکربندی برای خواندن.
registry_override_key	مکان رجیستری برای بررسی نادیده‌گیری‌ها. توجه داشته باشید که فقط پرونده پیکربندی توکار می‌تواند این تنظیم را تغییر دهد.
bundled_dir	پوشه‌ی فقط‌خواندنی حاوی پرونده‌های نهانگاه‌شده به‌صورت محلی.
install.fallback_source	مسیر یا URL یک ایندکس برای مراجعه در صورت عدم دسترسی به ایندکس اصلی.
install.enable_shortcut_kinds	فهرست جداشده با کاما از انواع میان‌برهای مجاز (مثلاً "pep514,start"). میان‌برهای فعال‌شده همچنان ممکن است توسط disable_shortcut_kinds غیرفعال شوند.
install.disable_shortcut_kinds	فهرست جداشده با کاما از انواع میان‌بر برای حذف (برای مثال "pep514,start"). میان‌برهای غیرفعال توسط enable_shortcut_kinds دوباره فعال نمی‌شوند.
install.hard_link_entrypoints	اگر true باشد، از پیوندهای سخت برای میان‌برهای سراسری استفاده می‌شود تا در فضای دیسک صرفه‌جویی شود. اگر false باشد، به‌جای آن هر پرونده اجرایی میان‌بر کپی می‌شود. پس از تغییر این تنظیم، برای به‌روزرسانی دستورهای موجود باید py install --refresh --force را اجرا کنید. به‌طور پیش‌فرض، true است. غیرفعال کردن این گزینه ممکن است برای عیب‌یابی یا سیستم‌هایی که با پیوندهای پرونده مشکل دارند، ضروری باشد.
pep514_root	محل رجیستری که ورودی‌های PEP 514 در آن خوانده و نوشته می‌شوند. به‌صورت پیش‌فرض HKEY_CURRENT_USER\Software\Python.
start_folder	پوشه‌ی منوی استارت که میان‌برها در آن نوشته می‌شوند. به‌طور پیش‌فرض، Python. این مسیر نسبت به پوشه‌ی Programs کاربر نسبی است.
virtual_env	مسیر محیط مجازی فعال. به‌طور پیش‌فرض این مقدار %VIRTUAL_ENV% است، اما می‌توان آن را خالی تنظیم کرد تا تشخیص venv غیرفعال شود.
shebang_can_run_anything_silently	اگر True باشد، هشدارهای قابل‌مشاهده هنگامی که خط مفسر برنامه‌ای غیر از ران‌تایم پایتون را راه‌اندازی می‌کند، سرکوب می‌شوند.
source_settings	نگاشتی از URL منبع به تنظیمات ویژه‌ی آن اندیس. هنگامی که چندین پرونده‌ی پیکربندی شامل این بخش باشند، تنظیمات URL افزوده یا بازنویسی می‌شوند، اما تنظیمات منفرد ادغام نمی‌شوند. این تنظیمات در حال حاضر فقط برای امضاهای اندیس هستند.

4.1.12. نصب پرونده‌های دودویی نخ‌آزاد

اضافه شده در نسخه‌ی 3.13.

توزیع‌های از پیش ساخته‌شده‌ی ساخت‌ نخ‌آزاد با نصب تگ‌های دارای پسوند t در دسترس هستند.

$> py install 3.14t
$> py install 3.14t-arm64
$> py install 3.14t-32

این به‌صورت عادی نصب و ثبت می‌شود. اگر هیچ ران‌تایم دیگری نصب نداشته باشید، python همین ران‌تایم را اجرا خواهد کرد. در غیر این صورت، باید از py -V:3.14t ... استفاده کنید، یا اگر پوشه‌ی نام‌های مستعار سراسری را به متغیر محیطی PATH خود افزوده باشید، از دستورهای python3.14t.exe استفاده کنید.

4.1.13. امضاهای اندیس

اضافه شده در نسخه‌ی 26.2.

پرونده‌های اندیس را می‌توان برای تشخیص دستکاری امضا کرد. امضا، پرونده کاتالوگی در همان URL اندیس است که .cat به نام پرونده آن افزوده شده است. پرونده کاتالوگ باید هش پرونده اندیس متناظر خود را در بر بگیرد و با یک امضای معتبر Authenticode امضا شده باشد. این امر به ابزارهای استاندارد (در ویندوز) امکان می‌دهد امضایی تولید کنند، و از هر گواهی می‌توان استفاده کرد، به شرط آن‌که سیستم‌عامل کلاینت از قبل به مرجع صدور گواهی آن (CA ریشه) اعتماد کرده باشد.

امضاهای ایندکس تنها زمانی دانلود و بررسی می‌شوند که بخش source_settings در پیکربندی محلی شامل URL ایندکس باشد و requires_signature برابر با true باشد، یا اینکه JSON ایندکس شامل requires_signature با مقدار true باشد. هنگامی که این تنظیم در پیکربندی محلی وجود داشته باشد، حتی اگر false باشد، تنظیمات موجود در ایندکس نادیده گرفته می‌شوند.

علاوه بر الزام به امضای معتبر، تنظیمات required_root_subject و required_publisher_subject می‌توانند امضاهای قابل قبول را بر اساس فیلدهای Subject گواهی، بیشتر محدود کنند. هر ویژگی‌ای که در پیکربندی تعیین شده باشد باید با ویژگی موجود در گواهی مطابقت داشته باشد (ویژگی‌های اضافی در گواهی نادیده گرفته می‌شوند). ویژگی‌های معمول عبارت‌اند از CN= برای نام متداول، O= برای واحد سازمانی، و C= برای کشور ناشر.

در نهایت، تنظیم required_publisher_eku اجازه می‌دهد الزام کنید که یک کاربرد کلید توسعه‌یافته (EKU) خاص به گواهی ناشر اختصاص داده‌شده باشد. برای مثال، EKU 1.3.6.1.5.5.7.3.3 نشان می‌دهد که گواهی برای امضای کد در نظر گرفته‌شده است (برخلاف احراز هویت سرور یا کلاینت). در ترکیب با یک مرجع صدور گواهی ریشه خاص، این امر سازوکار دیگری برای راستی‌آزمایی یک امضای معتبر فراهم می‌کند.

این یک نمونه بخش source_settings از یک پرونده پیکربندی است. در این حالت، ناشر فید به‌طور یکتا از طریق ترکیب ریشه‌ی Microsoft Identity Verification و EKU اختصاص‌یافته توسط آن ریشه شناسایی می‌شود. امضای مربوط به این حالت در https://www.python.org/ftp/python/index-windows.json.cat یافت می‌شود.

{
  "source_settings": {
    "https://www.python.org/ftp/python/index-windows.json": {
      "requires_signature": true,
      "required_root_subject": "CN=Microsoft Identity Verification Root Certificate Authority 2020",
      "required_publisher_subject": "CN=Python Software Foundation",
      "required_publisher_eku": "1.3.6.1.4.1.311.97.608394634.79987812.305991749.578777327"
    }
  }
}

همین تنظیمات را می‌توان به‌جای آن در پرونده‌ی index.json مشخص کرد. در این حالت، ریشه و EKU ذکر نمی‌شوند؛ به این معنا که امضا باید معتبر باشد و نام عمومی مشخصی در گواهی ناشر داشته باشد، اما از هیچ بررسی دیگری استفاده نمی‌شود.

{
  "requires_signature": true,
  "required_publisher_subject": "CN=Python Software Foundation",
  "versions": [
    // ...
  ]
}

هنگامی که تنظیمات درون یک فید (feed) استفاده می‌شوند، کاربر مطلع می‌شود و این تنظیمات در پرونده گزارش یا خروجی پرگویی (verbose) نمایش داده می‌شوند. توصیه می‌شود برای فیدهایی که مرتباً استفاده خواهند شد، این تنظیمات را در یک پرونده پیکربندی محلی کپی کنید تا تغییرهای غیرمجاز در فید نتوانند راستی‌آزمایی را از کار بیندازند.

نمی‌توان مکان پرونده‌ی امضا را در فید (feed) یا از طریق یک پرونده‌ی پیکربندی نادیده گرفت. مدیران می‌توانند source_settings خود را در یک پرونده‌ی پیکربندی الزامی ارائه کنند (به پیکربندی مدیریتی مراجعه کنید).

اگر اعتبارسنجی امضا شکست بخورد، به شما اطلاع داده می‌شود و از شما خواسته می‌شود که ادامه دهید. وقتی تأیید تعاملی مجاز نباشد (برای مثال، به این دلیل که --yes مشخص شده باشد)، همیشه لغو خواهد شد. در این سناریو، برای استفاده از فید (feed) با پیکربندی نامعتبر، باید پرونده پیکربندی‌ای ارائه دهید که بررسی امضا را برای آن فید غیرفعال کند.

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

4.1.14. Proxy settings

اضافه شده در نسخه‌ی 26.4.

By default, the Python install manager will use your system-wide proxy settings, including automatic authentication. For most users, this behaves the same as your browser and other applications.

To override the settings, use the NO_PROXY, HTTP_PROXY and HTTPS_PROXY environment variables. These should be set in the terminal session before using the Python install manager. Other applications may also use the variables, so use caution before setting them globally for your entire machine.

Setting NO_PROXY to any non-empty value will disable the use of any proxy. Use this to bypass your system's default proxy setting and attempt to access the index server directly.

Setting HTTPS_PROXY to a string like example.com:8080 will connect to that proxy server for all HTTPS connections. For the default index, all connections will be using HTTPS, and so this is the usual setting to override.

The HTTP_PROXY variable may be needed if you are using a private index server that does not use encrypted connections, but does require the default proxy server to be overridden. It follows the same format as HTTPS_PROXY.

Credentials may be embedded in either setting, however, when HTTPS_PROXY has credentials embedded they will be used in preference to other credentials. Only one set of credentials will be used for both types of proxy.

4.1.15. عیب‌یابی

اگر به‌نظر می‌رسد مدیر نصب پایتون شما به‌درستی کار نمی‌کند، لطفاً این آزمون‌ها و راه‌حل‌ها را گام‌به‌گام انجام دهید تا ببینید آیا کمک می‌کند یا خیر. اگر کمک نکرد، لطفاً مشکل را در رهگیر اشکال (bug tracker) ما گزارش کنید و هرگونه پرونده‌ی گزارش مرتبط را نیز ضمیمه کنید (که به‌طور پیش‌فرض در پوشه‌ی %TEMP% شما نوشته می‌شوند).

عیب‌یابی

نشانه	کارهایی برای امتحان کردن
وقتی python را در پایانهم تایپ می‌کنم، خطای «command not found» می‌گیرم یا اپلیکیشن Store باز می‌شود.	آیا مدیر نصب پایتون را نصب کرده‌اید؟
	روی Start کلیک کنید، «مدیریت نام‌های مستعار اجرای برنامه» (Manage app execution aliases) را باز کنید و بررسی کنید که نام‌های مستعار «Python (default)» فعال باشند. اگر از قبل فعال هستند، برای بازآوری فرمان، آن‌ها را غیرفعال و سپس دوباره فعال کنید. ممکن است فرمان‌های «Python (default windowed)» و «Python install manager» نیز نیاز به بازآوری داشته باشند.
	بررسی کنید که دستورهای py و pymanager کار می‌کنند.
	اطمینان حاصل کنید که متغیر PATH شما شامل ورودی %UserProfile%\AppData\Local\Microsoft\WindowsApps باشد. سیستم‌عامل این ورودی را به‌صورت پیش‌فرض یک‌بار، پس از سایر مسیرهای کاربر، در بر می‌گیرد. اگر حذف شود، میان‌برها یافت نخواهند شد.
وقتی py را در پایانه‌ام تایپ می‌کنم، خطای «command not found» می‌گیرم.	آیا مدیر نصب پایتون را نصب کرده‌اید؟
	روی Start کلیک کنید، «مدیریت نام‌های مستعار اجرای برنامه» (Manage app execution aliases) را باز کنید و بررسی کنید که نام‌های مستعار «Python (default)» فعال باشند. اگر از قبل فعال هستند، برای بازآوری فرمان، آن‌ها را غیرفعال و سپس دوباره فعال کنید. ممکن است فرمان‌های «Python (default windowed)» و «Python install manager» نیز نیاز به بازآوری داشته باشند.
	اطمینان حاصل کنید که متغیر PATH شما شامل ورودی %UserProfile%\AppData\Local\Microsoft\WindowsApps باشد. سیستم‌عامل این ورودی را به‌صورت پیش‌فرض یک‌بار، پس از سایر مسیرهای کاربر، در بر می‌گیرد. اگر حذف شود، میان‌برها یافت نخواهند شد.
وقتی فرمان‌ها را در پایانه‌ام تایپ می‌کنم، py خطای «can't open file» می‌دهد.	این معمولاً به این معنا است که راه‌انداز قدیمی را نصب کرده‌اید و این راه‌انداز نسبت به مدیر نصب پایتون اولویت دارد. برای حذف آن، روی Start کلیک کنید، «Installed apps» را باز کنید، عبارت «Python launcher» را جست‌وجو کنید و آن را حذف نصب کنید.
python همان ران‌تایم py را راه‌اندازی نمی‌کند	روی Start کلیک کنید، «برنامه‌های نصب‌شده» را باز کنید، به دنبال هر ران‌تایم پایتونِ موجود بگردید و یا آن‌ها را حذف کنید یا روی Modify کلیک کرده و گزینه‌های PATH را غیرفعال کنید.
	روی Start کلیک کنید، «مدیریت نام‌های مستعار اجرای برنامه» (Manage app execution aliases) را باز کنید و بررسی کنید که نام مستعار python.exe شما روی «Python (default)» تنظیم شده باشد
python و py ران‌تایم مورد انتظار من را راه‌اندازی نمی‌کنند	متغیر محیطی PYTHON_MANAGER_DEFAULT یا پیکربندی default_tag خود را بررسی کنید. دستور py list پیش‌فرض شما را بر اساس این تنظیمات نمایش می‌دهد.
	نصب‌هایی که توسط مدیر نصب پایتون مدیریت می‌شوند، پیش از نصب‌های مدیریت‌نشده انتخاب خواهند شد. برای نصب ران‌تایم مورد انتظار خود از py install استفاده کنید، یا تگ پیش‌فرض خود را پیکربندی کنید.
	نصب‌های پیش‌انتشار و آزمایشی که توسط مدیر نصب پایتون مدیریت نمی‌شوند، ممکن است مقدم بر نسخه‌های پایدار انتخاب شوند. برچسب پیش‌فرض خود را پیکربندی کنید یا ران‌تایم پیش‌انتشار را حذف نصب کرده و آن را با استفاده از py install دوباره نصب کنید.
pythonw یا pyw همان ران‌تایمی را که python یا py راه‌اندازی می‌کنند، راه‌اندازی نمی‌کنند	روی Start کلیک کنید، «Manage app execution aliases» را باز کنید و بررسی کنید که نام‌های مستعار pythonw.exe و pyw.exe شما با سایر مواردتان سازگار باشند.
وقتی pip را در پایانه‌ام تایپ می‌کنم، خطای "command not found" دریافت می‌کنم.	آیا یک محیط مجازی را فعال کرده‌اید؟ برای فعال‌سازی، اسکریپت .venv\Scripts\activate را در پایانه خود اجرا کنید.
	ممکن است بسته موجود باشد، اما پرونده اجراییِ تولیدشده را نداشته باشد. به‌جای آن، توصیه می‌کنیم از دستور python -m pip استفاده کنید. اجرای py install --refresh و اطمینان از اینکه پوشه‌ی میانبرهای سراسری روی PATH قرار دارد (اگر روی آن نباشد، در خروجی دستور نمایش داده می‌شود) باید دستورهایی مانند pip (و سایر بسته‌های نصب‌شده) را در دسترس قرار دهد.
من بسته‌ای را با pip نصب کردم، اما فرمان آن پیدا نمی‌شود.	آیا یک محیط مجازی را فعال کرده‌اید؟ برای فعال‌سازی، اسکریپت .venv\Scripts\activate را در پایانه خود اجرا کنید.
	میان‌برهای سراسری برای بسته‌های جدید به‌طور خودکار توسط مدیر نصب پایتون ایجاد نمی‌شوند. به‌طور مشابه، میان‌برهای بسته‌های حذف‌شده نیز پاک نمی‌شوند. برای به‌روزرسانی میان‌برهای سراسری بسته‌های تازه نصب‌شده، دستور py install --refresh را اجرا کنید.
با نوشتن script-name.py در پایانه، آن در یک پنجره‌ی جدید باز می‌شود.	این یک محدودیت شناخته‌شده‌ی سیستم‌عامل است. یا py را پیش از نام اسکریپت مشخص کنید، یا یک پرونده‌ی دسته‌ای (batch file) هم‌نام با اسکریپت و حاوی @py "%~dpn0.py" %* بسازید، یا legacy launcher را نصب کنید و آن را به‌عنوان پیوند (association) برای اسکریپت‌ها انتخاب کنید.
کشیدن و رها کردن پرونده‌ها روی یک اسکریپت کار نمی‌کند	این یک محدودیت شناخته‌شده‌ی سیستم‌عامل است. این قابلیت با legacy launcher یا با مدیر نصب پایتون هنگامی که از MSI نصب شده باشد، پشتیبانی می‌شود.
مدیر نصب پایتون را چندین بار نصب کرده‌ام.	می‌توان به‌طور همزمان از Store یا WinGet، از MSIX در وب‌سایت پایتون و از MSI نصب کرد. همه‌ی آن‌ها با یکدیگر سازگارند و پیکربندی و ران‌تایم‌ها را به اشتراک خواهند گذاشت.
	برای حذف مدیر نصب به روش‌هایی غیر از صفحه‌ی تنظیمات معمول برنامه‌های نصب‌شده (Installed Apps) (افزودن و حذف برنامه‌ها)، به بخش نصب پیشرفته که پیش‌تر آمده است مراجعه کنید.
تنظیمات قدیمی py.ini من دیگر کار نمی‌کنند.	مدیر نصب جدید پایتون دیگر از این پرونده پیکربندی یا تنظیمات آن پشتیبانی نمی‌کند و بنابراین نادیده گرفته خواهد شد. برای اطلاعات درباره‌ی تنظیمات پیکربندی به پیکربندی مراجعه کنید.

4.2. بسته‌ی تعبیه‌پذیر

اضافه شده در نسخه‌ی 3.5.

توزیع تعبیه‌شده یک پرونده ZIP حاوی یک محیط حداقلی پایتون است. این توزیع برای عمل کردن به عنوان بخشی از یک برنامه دیگر در نظر گرفته شده است، نه اینکه کاربران نهایی مستقیماً به آن دسترسی داشته باشند.

برای نصب یک توزیع تعبیه‌شده، توصیه می‌کنیم از py install همراه با گزینه‌ی --target استفاده کنید:

$> py install 3.14-embed --target=<directory>

پس از استخراج، توزیع تعبیه‌شده (تقریباً) به‌طور کامل از سیستم کاربر ایزوله می‌شود، از جمله متغیرهای محیطی، تنظیمات رجیستری سیستم و بسته‌های نصب‌شده. کتابخانه استاندارد به‌صورت پرونده‌های .pyc از پیش کامپایل‌شده و بهینه‌شده در یک ZIP گنجانده شده است و python3.dll، python313.dll، python.exe و pythonw.exe همگی ارائه شده‌اند. Tcl/tk (شامل همه‌ی موارد وابسته به آن، مانند Idle)، pip و مستندات پایتون گنجانده نشده‌اند.

یک پرونده ._pth پیش‌فرض گنجانده شده است که مسیرهای جستجوی پیش‌فرض را بیشتر محدود می‌کند (همان‌طور که در یافتن ماژول‌ها در ادامه توضیح داده شده است). این پرونده برای آن در نظر گرفته شده است که جاسازان (embedders) در صورت نیاز آن را تغییر دهند.

بسته‌های شخص ثالث باید توسط نصب‌کننده‌ی برنامه، در کنار توزیع تعبیه‌شده (embedded distribution) نصب شوند. استفاده از pip برای مدیریت وابستگی‌ها، مانند یک نصب معمولی پایتون، در این توزیع پشتیبانی نمی‌شود، هرچند با کمی دقت ممکن است بتوان pip را برای به‌روزرسانی‌های خودکار گنجاند و از آن استفاده کرد. به‌طور کلی، بسته‌های شخص ثالث باید به‌عنوان بخشی از برنامه در نظر گرفته شوند ("vendoring") تا توسعه‌دهنده بتواند پیش از ارائه‌ی به‌روزرسانی‌ها به کاربران، از سازگاری با نسخه‌های جدیدتر اطمینان حاصل کند.

دو مورد استفاده‌ی توصیه‌شده برای این توزیع در زیر توضیح داده شده‌اند.

4.2.1. برنامه پایتون

برنامه‌ای که با پایتون نوشته شده است، لزوماً نیازی ندارد که کاربران از این واقعیت آگاه باشند. در این حالت می‌توان از توزیع تعبیه‌شده برای گنجاندن نسخه‌ای خصوصی از پایتون در بسته‌ی نصب استفاده کرد. بسته به اینکه چقدر باید شفاف باشد (یا برعکس، چقدر باید حرفه‌ای به نظر برسد)، دو گزینه وجود دارد.

استفاده از یک پرونده اجرایی تخصصی به‌عنوان راه‌انداز، به مقداری کدنویسی نیاز دارد، اما شفاف‌ترین تجربه را برای کاربران فراهم می‌کند. با یک راه‌انداز سفارشی، هیچ نشانه واضحی وجود ندارد که نشان دهد برنامه روی پایتون اجرا می‌شود: می‌توان آیکون‌ها را سفارشی کرد، اطلاعات شرکت و نسخه را مشخص کرد و ارتباط پرونده‌ها به‌درستی کار می‌کند. در بیشتر موارد، یک راه‌انداز سفارشی تنها باید بتواند Py_Main را با یک خط فرمان هاردکد‌شده فراخوانی کند.

رویکرد ساده‌تر، فراهم کردن یک پرونده‌ی دسته‌ای (batch file) یا میان‌بر تولیدشده است که مستقیماً python.exe یا pythonw.exe را با آرگومان‌های خط فرمان مورد نیاز فراخوانی می‌کند. در این حالت، برنامه به‌جای نام واقعی خود، به‌صورت پایتون نمایش داده می‌شود و کاربران ممکن است در تمایز آن از سایر فرایندهای در حال اجرای پایتون یا پیوندهای پرونده (file associations) دچار مشکل شوند.

با رویکرد دوم، بسته‌ها باید به‌صورت پوشه در کنار پرونده اجرایی پایتون نصب شوند تا از دسترسی‌پذیری آن‌ها در مسیر اطمینان حاصل شود. با راه‌انداز اختصاصی، بسته‌ها می‌توانند در مکان‌های دیگر قرار گیرند، زیرا پیش از راه‌اندازی برنامه امکان تعیین مسیر جستجو وجود دارد.

4.2.2. تعبیه پایتون

برنامه‌های نوشته‌شده به کد بومی اغلب به نوعی زبان اسکریپت‌نویسی نیاز دارند و می‌توان از توزیع تعبیه‌شده پایتون برای این منظور استفاده کرد. به‌طور کلی، بخش عمده‌ی برنامه به کد بومی است و بخشی از آن یا python.exe را فراخوانی می‌کند یا مستقیماً از python3.dll استفاده می‌کند. در هر دو حالت، استخراج توزیع تعبیه‌شده در زیرپوشه‌ای از محل نصب برنامه برای فراهم کردن یک مفسر پایتون قابل بارگذاری کافی است.

مانند کاربرد در برنامه، بسته‌ها را می‌توان در هر مکانی نصب کرد، زیرا پیش از مقداردهی اولیه مفسر، امکان تعیین مسیرهای جستجو وجود دارد. به‌جز این، هیچ تفاوت بنیادی میان استفاده از توزیع تعبیه‌شده و یک نصب معمولی وجود ندارد.

4.3. بسته‌های nuget.org

اضافه شده در نسخه‌ی 3.5.2.

بسته‌ی nuget.org یک محیط پایتون با حجم کاهش‌یافته است که برای استفاده در سیستم‌های یکپارچه‌سازی مستمر و ساخت بدون نصب سراسری پایتون در نظر گرفته شده است. اگرچه nuget «مدیر بسته‌ی .NET» است، برای بسته‌های حاوی ابزارهای زمان ساخت نیز کاملاً خوب کار می‌کند.

برای به‌روزترین اطلاعات درباره‌ی استفاده از nuget به nuget.org مراجعه کنید. آنچه در ادامه می‌آید، خلاصه‌ای است که برای توسعه‌دهندگان پایتون کافی است.

ابزار خط فرمان nuget.exe را می‌توان مستقیماً از https://dist.nuget.org/win-x86-commandline/latest/nuget.exe دانلود کرد، برای مثال با استفاده از curl یا PowerShell. با این ابزار، آخرین نسخه‌ی پایتون برای ماشین‌های ۶۴ بیتی یا ۳۲ بیتی با استفاده از دستور زیر نصب می‌شود:

nuget.exe install python -ExcludeVersion -OutputDirectory .
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .

برای انتخاب نسخه‌ی خاصی، -Version 3.x.y را اضافه کنید. پوشه‌ی خروجی را می‌توان از . تغییر داد و بسته در یک زیرپوشه نصب خواهد شد. به‌طور پیش‌فرض، نام زیرپوشه همان نام بسته است و بدون گزینه‌ی -ExcludeVersion، این نام شامل نسخه‌ی مشخص نصب‌شده خواهد بود. درون زیرپوشه، پوشه‌ی tools قرار دارد که شامل نصب پایتون است:

# Without -ExcludeVersion
> .\python.3.5.2\tools\python.exe -V
Python 3.5.2

# With -ExcludeVersion
> .\python\tools\python.exe -V
Python 3.5.2

به‌طور کلی، بسته‌های nuget قابل ارتقا نیستند و نسخه‌های جدیدتر باید به‌صورت کنار‌هم نصب شوند و با استفاده از مسیر کامل به آن‌ها ارجاع داده شود. به‌عنوان جایگزین، می‌توانید پوشه‌ی بسته را به‌صورت دستی حذف کنید و دوباره آن را نصب کنید. بسیاری از سیستم‌های CI در صورتی که پرونده‌ها را بین ساخت‌ها حفظ نکنند، این کار را به‌طور خودکار انجام می‌دهند.

در کنار پوشه‌ی tools یک پوشه‌ی build\native قرار دارد. این پوشه شامل یک پرونده‌ی ویژگی‌های MSBuild با نام python.props است که می‌توان از آن در یک پروژه‌ی C++ برای ارجاع به نصب پایتون استفاده کرد. با گنجاندن این تنظیمات، سرآیندها و کتابخانه‌های ایمپورت به‌طور خودکار در ساخت شما استفاده می‌شوند.

صفحات اطلاعات بسته در nuget.org عبارت‌اند از www.nuget.org/packages/python برای نسخه‌ی ۶۴ بیتی، www.nuget.org/packages/pythonx86 برای نسخه‌ی ۳۲ بیتی و www.nuget.org/packages/pythonarm64 برای نسخه‌ی ARM64

4.3.1. بسته‌های نخ‌آزاد

اضافه شده در نسخه‌ی 3.13.

بسته‌های حاوی پرونده‌های دودویی نخ‌آزاد به این صورت نام‌گذاری می‌شوند: python-freethreaded برای نسخه‌ی ۶۴ بیتی، pythonx86-freethreaded برای نسخه‌ی ۳۲ بیتی و pythonarm64-freethreaded برای نسخه‌ی ARM64. این بسته‌ها هر دو نقطه‌ی ورود python3.13t.exe و python.exe را در بر می‌گیرند که هر دو به صورت نخ‌آزاد اجرا می‌شوند.

4.4. بسته‌های جایگزین

علاوه بر توزیع استاندارد سی‌پایتون، بسته‌های تغییریافته‌ای نیز وجود دارند که قابلیت‌های اضافی را در بر می‌گیرند. در ادامه، فهرستی از نسخه‌های محبوب و ویژگی‌های کلیدی آن‌ها آمده است:

ActivePython

نصب‌کننده با سازگاری چندسکویی، مستندات، PyWin32

Anaconda

ماژول‌های علمی محبوب (مانند numpy، scipy و pandas) و مدیر بسته‌ی conda.

Enthought Deployment Manager

«محیط و مدیر بسته نسل بعدی پایتون».

پیش‌تر Enthought محصول Canopy را ارائه می‌کرد، اما این محصول در سال ۲۰۱۶ به پایان عمر خود رسید.

WinPython

توزیع مخصوص ویندوز همراه با بسته‌های علمی پیش‌ساخته و ابزارهایی برای ساخت بسته‌ها.

توجه داشته باشید که این بسته‌ها ممکن است شامل آخرین نسخه‌های پایتون یا کتابخانه‌های دیگر نباشند و توسط تیم اصلی پایتون نگهداری یا پشتیبانی نمی‌شوند.

4.5. نسخه‌های پشتیبانی‌شده ویندوز

همان‌طور که در PEP 11 مشخص شده است، یک نسخه‌ی پایتون تنها تا زمانی از یک پلتفرم ویندوز پشتیبانی می‌کند که مایکروسافت آن پلتفرم را مشمول پشتیبانی توسعه‌یافته (extended support) بداند. این بدان معناست که پایتون 3.14 از ویندوز 10 و جدیدتر پشتیبانی می‌کند. اگر به پشتیبانی از ویندوز 7 نیاز دارید، لطفاً پایتون 3.8 را نصب کنید. اگر به پشتیبانی از ویندوز 8.1 نیاز دارید، لطفاً پایتون 3.12 را نصب کنید.

4.6. حذف محدودیت MAX_PATH

ویندوز به‌طور تاریخی طول مسیرها را به ۲۶۰ نویسه محدود کرده بود. این بدان معنا بود که مسیرهای بلندتر از این مقدار حل نمی‌شدند و خطا رخ می‌داد.

در آخرین نسخه‌های ویندوز، این محدودیت را می‌توان تا بیش از ۳۲٬۰۰۰ نویسه افزایش داد. مدیر شما باید سیاست گروهی «فعال‌سازی مسیرهای بلند Win32» (Enable Win32 long paths) را فعال کند، یا مقدار LongPathsEnabled را در کلید رجیستری HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem برابر 1 قرار دهد.

این امر به تابع open()، ماژول os و بیشتر سایر قابلیت‌های مسیر اجازه می‌دهد تا مسیرهای بلندتر از ۲۶۰ نویسه را بپذیرند و بازگردانند.

پس از تغییر گزینه‌ی بالا و راه‌اندازی مجدد، هیچ پیکربندی دیگری لازم نیست.

4.7. حالت UTF-8

اضافه شده در نسخه‌ی 3.7.

ویندوز همچنان از کدگذاری‌های قدیمی برای کدگذاری سیستم (صفحه‌ی کد ANSI) استفاده می‌کند. پایتون از آن برای کدگذاری پیش‌فرض پرونده‌های متنی استفاده می‌کند (برای مثال locale.getencoding()).

این ممکن است مشکلاتی ایجاد کند، زیرا UTF-8 به‌طور گسترده در اینترنت و بیشتر سیستم‌های یونیکس، از جمله WSL (زیرسیستم ویندوز برای لینوکس)، استفاده می‌شود.

می‌توانید از حالت UTF-8 پایتون برای تغییر کدگذاری متن پیش‌فرض به UTF-8 استفاده کنید. می‌توانید حالت UTF-8 پایتون را از طریق گزینه‌ی خط فرمان -X utf8 یا متغیر محیطی PYTHONUTF8=1 فعال کنید. برای فعال کردن حالت UTF-8 به PYTHONUTF8 و برای نحوه‌ی تغییر متغیرهای محیطی به مدیر نصب پایتون مراجعه کنید.

وقتی حالت UTF-8 پایتون فعال باشد، شما همچنان می‌توانید از کدگذاری سیستم (صفحه‌ی کد ANSI) از طریق کدک «mbcs» استفاده کنید.

توجه داشته باشید که افزودن PYTHONUTF8=1 به متغیرهای محیطی پیش‌فرض، بر تمام برنامه‌های Python 3.7+ در سیستم شما تأثیر می‌گذارد. اگر برنامه‌هایی از Python 3.7+ دارید که به کدگذاری قدیمی سیستم متکی هستند، توصیه می‌شود متغیر محیطی را به‌صورت موقت تنظیم کنید یا از گزینه‌ی خط فرمان -X utf8 استفاده کنید.

توجه

حتی زمانی که حالت UTF-8 غیرفعال است، پایتون به‌طور پیش‌فرض در ویندوز برای موارد زیر از UTF-8 استفاده می‌کند:

• ورودی/خروجی کنسول شامل ورودی/خروجی استاندارد (برای جزئیات به PEP 528 مراجعه کنید).

• کدگذاری سامانه فایل‌بندی (برای جزئیات به PEP 529 مراجعه کنید).

4.8. یافتن ماژول‌ها

این یادداشت‌ها توضیحات موجود در مقداردهی اولیه‌ی مسیر جستجوی ماژول sys.path را با یادداشت‌های تفصیلی ویندوز تکمیل می‌کنند.

وقتی هیچ پرونده‌ی ._pth یافت نشود، sys.path در ویندوز به این صورت پر می‌شود:

• یک ورودی خالی در ابتدا افزوده می‌شود که متناظر با پوشه جاری است.

• اگر متغیر محیطی PYTHONPATH وجود داشته باشد، همان‌طور که در متغیرهای محیطی توضیح داده شده است، ورودی‌های آن در ادامه افزوده می‌شوند. توجه داشته باشید که در ویندوز، مسیرها در این متغیر باید با نقطه‌ویرگول از یکدیگر جدا شوند تا از دونقطه‌ی به‌کاررفته در شناسه‌های درایو (C:\ و غیره) متمایز باشند.

• می‌توان «مسیرهای برنامه» اضافی را در رجیستری، به‌صورت زیرکلیدهایی از \SOFTWARE\Python\PythonCore{version}\PythonPath، زیر هر دو کندو (hive) HKEY_CURRENT_USER و HKEY_LOCAL_MACHINE افزود. زیرکلیدهایی که مقدار پیش‌فرض آن‌ها رشته‌ای از مسیرهای جداشده با نقطه‌ویرگول است، باعث می‌شوند هر مسیر به sys.path افزوده شود. (توجه داشته باشید که همه‌ی نصاب‌های شناخته‌شده فقط از HKLM استفاده می‌کنند، بنابراین HKCU معمولاً خالی است.)

• اگر متغیر محیطی PYTHONHOME تنظیم شده باشد، به عنوان «خانه‌ی پایتون» (Python Home) فرض می‌شود. در غیر این صورت، مسیر پرونده اجرایی اصلی پایتون برای یافتن یک «پرونده‌ی نشانه» (landmark file) (یا Lib\os.py یا pythonXY.zip) به کار می‌رود تا «خانه‌ی پایتون» استنباط شود. اگر خانه‌ی پایتون پیدا شود، زیرپوشه‌های مرتبطی که به sys.path اضافه می‌شوند (Lib، plat-win و غیره) بر اساس آن پوشه هستند. در غیر این صورت، مسیر هسته‌ی پایتون از PythonPath ذخیره‌شده در رجیستری ساخته می‌شود.

• اگر خانه‌ی پایتون (Python Home) پیدا نشود، هیچ PYTHONPATH در محیط مشخص نشده باشد و هیچ ورودی‌ای در رجیستری یافت نشود، از یک مسیر پیش‌فرض با ورودی‌های نسبی استفاده می‌شود (مثلاً .\Lib;.\plat-win و غیره).

اگر پرونده‌ی pyvenv.cfg در کنار پرونده‌ی اجرایی اصلی یا در پوشه‌ی یک سطح بالاتر از آن یافت شود، تغییرات زیر اعمال می‌شوند:

• اگر home یک مسیر مطلق باشد و PYTHONHOME تنظیم نشده باشد، این مسیر هنگام استنتاج مکان home به‌جای مسیر پرونده اجرایی اصلی استفاده می‌شود.

نتیجه نهایی همه‌ی این‌ها این است:

• هنگام اجرای python.exe یا هر پرونده .exe دیگری در پوشه‌ی اصلی پایتون (چه نسخه‌ی نصب‌شده، چه مستقیماً از پوشه‌ی PCbuild)، مسیر هسته استنتاج می‌شود و مسیرهای هسته در رجیستری نادیده گرفته می‌شوند. سایر «مسیرهای اپلیکیشن» (application paths) در رجیستری همیشه خوانده می‌شوند.

• وقتی پایتون در یک .exe دیگر میزبانی شود (پوشه‌ی متفاوت، تعبیه‌شده از طریق COM و غیره)، «Python Home» تشخیص داده نخواهد شد، بنابراین از مسیر اصلیِ رجیستری استفاده می‌شود. سایر «مسیرهای برنامه» در رجیستری همواره خوانده می‌شوند.

• اگر پایتون نتواند خانه‌ی خود را پیدا کند و هیچ مقداری در رجیستری وجود نداشته باشد (exe فریزشده، برخی تنظیمات نصب بسیار عجیب)، مسیری دریافت می‌کنید که شامل چند مسیر پیش‌فرض اما نسبی است.

برای کسانی که می‌خواهند پایتون را همراه برنامه یا توزیع خود بسته‌بندی کنند، توصیه‌های زیر از تعارض با نصب‌های دیگر جلوگیری می‌کند:

• یک پرونده ._pth در کنار پرونده اجرایی خود قرار دهید که پوشه‌هایی را که باید گنجانده شوند در بر می‌گیرد. این کار مسیرهای فهرست‌شده در رجیستری و متغیرهای محیطی را نادیده می‌گیرد و site را نیز نادیده می‌گیرد، مگر اینکه import site فهرست شده باشد.

• اگر python3.dll یا python37.dll را در پرونده اجرایی خودتان بارگذاری می‌کنید، پیش از Py_InitializeFromConfig()، PyConfig.module_search_paths را به‌طور صریح تنظیم کنید.

• پیش از راه‌اندازی python.exe از برنامه‌ی خود، PYTHONPATH را پاک و/یا بازنویسی کنید و PYTHONHOME را تنظیم کنید.

• اگر نمی‌توانید از پیشنهادهای قبلی استفاده کنید (برای مثال، شما توزیعی هستید که به افراد اجازه می‌دهد python.exe را مستقیماً اجرا کنند)، مطمئن شوید که پرونده نشانه (landmark) یعنی Lib\os.py در پوشه‌ی نصب شما وجود دارد. (توجه داشته باشید که این پرونده درون یک پرونده ZIP شناسایی نمی‌شود، اما در عوض یک پرونده ZIP با نام صحیح شناسایی می‌شود.)

این موارد تضمین می‌کنند که پرونده‌های موجود در یک نصب سراسری سیستم، بر نسخه‌ای از کتابخانه استاندارد که همراه برنامه‌ی شما بسته‌بندی شده است، تقدم پیدا نکنند. در غیر این صورت، ممکن است کاربرانتان هنگام استفاده از برنامه‌ی شما با مشکلاتی مواجه شوند. توجه داشته باشید که نخستین پیشنهاد بهترین گزینه است، زیرا موارد دیگر ممکن است همچنان در برابر مسیرهای غیراستاندارد در رجیستری و site-packages کاربر آسیب‌پذیر باشند.

تغییر یافته در نسخه‌ی 3.6: افزودن پشتیبانی از پرونده‌ی ._pth و حذف گزینه‌ی applocal از pyvenv.cfg.

تغییر یافته در نسخه‌ی 3.6: افزودن pythonXX.zip به‌عنوان یک نشانه (landmark) بالقوه هنگامی که مستقیماً مجاور پرونده اجرایی باشد.

منسوخ شده از نسخه‌ی 3.6: ماژول‌های مشخص‌شده در رجیستری زیر Modules (نه PythonPath) ممکن است توسط importlib.machinery.WindowsRegistryFinder ایمپورت شوند. این یابنده در ویندوز در نسخه‌های 3.6.0 و قبل از آن فعال است، اما ممکن است در آینده لازم باشد به‌طور صریح به sys.meta_path افزوده شود.

4.9. ماژول‌های اضافی

با اینکه هدف پایتون قابل حمل بودن میان همه‌ی سکوهاست، ویژگی‌هایی وجود دارند که مختص ویندوز هستند. چند ماژول، هم در کتابخانه استاندارد و هم خارج از آن، و قطعه‌کدهایی برای استفاده از این ویژگی‌ها وجود دارند.

ماژول‌های استاندارد مخصوص ویندوز در سرویس‌های خاص MS Windows مستند شده‌اند.

4.9.1. PyWin32

ماژول PyWin32 نوشته‌ی مارک هموند، مجموعه‌ای از ماژول‌ها برای پشتیبانی پیشرفته‌ی مخصوص ویندوز است. این شامل ابزارهایی برای موارد زیر است:

• مدل شیء کامپوننت (COM)

• فراخوانی‌های Win32 API

• رجیستری

• گزارش رویداد

• رابط‌های کاربریِ Microsoft Foundation Classes (MFC)

PythonWin یک برنامه‌ی نمونه‌ی MFC است که همراه PyWin32 ارائه می‌شود. این یک IDE قابل تعبیه با اشکال‌زدای توکار است.

همچنین ملاحظه نمائید

چگونه در Win32 انجام دهم...؟

نوشته‌ی تیم گلدن

Python and COM

به قلم دیوید و پل بودی

4.9.2. cx_Freeze

cx_Freeze اسکریپت‌های پایتون را در برنامه‌های اجرایی ویندوز (پرونده‌های *.exe) دربر می‌گیرد. پس از انجام این کار، می‌توانید برنامه خود را توزیع کنید، بدون آنکه کاربران شما نیازی به نصب پایتون داشته باشند.

4.10. کامپایل کردن پایتون روی ویندوز

اگر می‌خواهید سی‌پایتون را خودتان کامپایل کنید، نخستین کاری که باید انجام دهید این است که کد منبع را دریافت کنید. می‌توانید یا کد منبع آخرین نسخه را دانلود کنید یا صرفاً یک چک‌اوت (checkout) تازه بگیرید.

درخت منبع شامل یک راه‌حل ساخت (build solution) و پرونده‌های پروژه برای Microsoft Visual Studio است؛ این همان کامپایلری است که برای ساخت نسخه‌های رسمی پایتون استفاده می‌شود. این پرونده‌ها در پوشه‌ی PCbuild قرار دارند.

برای اطلاعات کلی درباره‌ی فرایند ساخت، به PCbuild/readme.txt مراجعه کنید.

برای ماژول‌های توسعه‌ای، به ساخت ماژول‌های توسعه‌ای C و ++C در ویندوز مراجعه کنید.

4.11. نصب‌کننده‌ی کامل (منسوخ)

منسوخ شده از نسخه‌ی 3.14: این نصب‌کننده از نسخه 3.14 منسوخ شده است و برای پایتون 3.16 یا جدیدتر تولید نخواهد شد. برای نصب‌کننده‌ی مدرن به مدیر نصب پایتون مراجعه کنید.

4.11.1. مراحل نصب

چهار نصب‌کننده‌ی پایتون 3.14 برای دانلود در دسترس است - دو مورد برای هر یک از نسخه‌های ۳۲ بیتی و ۶۴ بیتی مفسر. نصب‌کننده‌ی وب حجم دانلود اولیه‌ی کوچکی دارد و کامپوننت‌های مورد نیاز را در صورت نیاز به‌طور خودکار دانلود می‌کند. نصب‌کننده‌ی آفلاین شامل کامپوننت‌های لازم برای نصب پیش‌فرض است و تنها برای قابلیت‌های اختیاری به اتصال اینترنت نیاز دارد. برای روش‌های دیگر پرهیز از دانلود در حین نصب، به نصب بدون دانلود مراجعه کنید.

پس از راه‌اندازی نصب‌کننده، می‌توان یکی از دو گزینه را انتخاب کرد:

اگر «Install Now» را انتخاب کنید:

• شما نیازی به مدیر سیستم بودن نخواهید داشت (مگر آنکه به‌روزرسانی سیستم برای کتابخانه‌ی ران‌تایم C لازم باشد یا مدیر نصب پایتون را برای همه کاربران نصب کنید)

• پایتون در پوشه‌ی کاربری شما نصب خواهد شد

• مدیر نصب پایتون بر اساس گزینه‌ی موجود در پایین صفحه‌ی نخست نصب خواهد شد

• کتابخانه استاندارد، بدنه آزمون‌ها، راه‌انداز و pip نصب خواهند شد

• در صورت انتخاب، پوشه‌ی نصب به PATH شما اضافه خواهد شد

• میان‌برها فقط برای کاربر فعلی قابل مشاهده خواهند بود

انتخاب گزینه‌ی «سفارشی‌سازی نصب» (Customize installation) به شما امکان می‌دهد قابلیت‌هایی که نصب می‌شوند، محل نصب و سایر گزینه‌ها یا کنش‌های پس از نصب را انتخاب کنید. برای نصب نمادهای اشکال‌زدایی یا پرونده‌های دودویی، باید از این گزینه استفاده کنید.

برای انجام نصب برای همه‌ی کاربران، باید «سفارشی‌سازی نصب» را انتخاب کنید. در این حالت:

• ممکن است لازم باشد اعتبارنامه‌های مدیریتی یا تأیید خود را ارائه کنید

• پایتون در پوشه‌ی Program Files نصب خواهد شد

• مدیر نصب پایتون در پوشه‌ی ویندوز نصب خواهد شد

• ویژگی‌های اختیاری را می‌توان در حین نصب انتخاب کرد

• کتابخانه استاندارد می‌تواند از پیش به بایت‌کد کامپایل شود

• در صورت انتخاب، پوشه نصب به PATH سیستم افزوده خواهد شد

• میان‌برها برای همه کاربران در دسترس هستند

4.11.2. حذف محدودیت MAX_PATH

ویندوز به‌طور تاریخی طول مسیرها را به ۲۶۰ نویسه محدود کرده بود. این بدان معنا بود که مسیرهای بلندتر از این مقدار حل نمی‌شدند و خطا رخ می‌داد.

در جدیدترین نسخه‌های ویندوز، این محدودیت را می‌توان تا حدود ۳۲٬۰۰۰ نویسه افزایش داد. مدیر شما باید سیاست گروهی «Enable Win32 long paths» را فعال کند، یا LongPathsEnabled را در کلید رجیستری HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem برابر 1 قرار دهد.

این امر به تابع open()، ماژول os و بیشتر سایر قابلیت‌های مسیر اجازه می‌دهد تا مسیرهای بلندتر از ۲۶۰ نویسه را بپذیرند و بازگردانند.

پس از تغییر گزینه‌ی بالا، هیچ پیکربندی دیگری لازم نیست.

تغییر یافته در نسخه‌ی 3.6: پشتیبانی از مسیرهای طولانی در پایتون فعال شد.

4.11.3. نصب بدون رابط کاربری

تمام گزینه‌های موجود در رابط کاربری نصب‌کننده را می‌توان از طریق خط فرمان نیز مشخص کرد؛ این کار به نصب‌کننده‌های مبتنی بر اسکریپت امکان می‌دهد بدون تعامل کاربر، یک نصب را روی تعداد زیادی رایانه بازتولید کنند. همچنین می‌توان این گزینه‌ها را بدون پنهان کردن رابط کاربری، به منظور تغییر برخی از پیش‌فرض‌ها تنظیم کرد.

گزینه‌های زیر (که با اجرای نصب‌کننده به همراه /? یافت می‌شوند) را می‌توان به نصب‌کننده ارسال کرد:

نام	توضیحات
/passive	برای نمایش پیشرفت بدون نیاز به تعامل کاربر
/quiet	برای نصب/حذف نصب بدون نمایش هیچ‌گونه رابط کاربری
/simple	برای جلوگیری از سفارشی‌سازی توسط کاربر
/uninstall	برای حذف پایتون (بدون تأیید)
/layout [directory]	برای پیش‌دانلود همه‌ی اجزا
/log [filename]	برای مشخص کردن مکان پرونده‌های گزارش

سایر گزینه‌ها به صورت name=value ارسال می‌شوند؛ مقدار آن معمولاً 0 برای غیرفعال کردن یک قابلیت، 1 برای فعال کردن یک قابلیت، یا یک مسیر است. فهرست کامل گزینه‌های موجود در ادامه نمایش داده شده است.

نام	توضیحات	پیش‌فرض
InstallAllUsers	انجام یک نصب سراسری.	0
TargetDir	پوشه‌ی نصب	بر اساس InstallAllUsers انتخاب می‌شود
DefaultAllUsersTargetDir	پوشه‌ی نصب پیش‌فرض برای نصب‌های همه‌ی کاربران	%ProgramFiles%\Python X.Y یا %ProgramFiles(x86)%\Python X.Y
DefaultJustForMeTargetDir	پوشه‌ی نصب پیش‌فرض برای نصب‌های «فقط برای من»	%LocalAppData%\Programs\Python\PythonXY یا %LocalAppData%\Programs\Python\PythonXY-32 یا %LocalAppData%\Programs\Python\PythonXY-64
DefaultCustomTargetDir	پوشه‌ی پیش‌فرض نصب سفارشی که در رابط کاربری نمایش داده می‌شود	(خالی)
AssociateFiles	در صورتی که راه‌انداز نیز نصب شده باشد، پیوندهای پرونده ایجاد می‌شوند.	1
CompileAll	تمام پرونده‌های .py را به .pyc کامپایل کنید.	0
PrependPath	پوشه‌های نصب و Scripts را به ابتدای PATH اضافه کنید و .PY را به PATHEXT بیفزایید	0
AppendPath	پوشه‌های install و Scripts را به PATH اضافه کنید و .PY را به PATHEXT بیفزایید	0
Shortcuts	در صورت نصب بودن، میان‌برهایی برای مفسر، مستندات و IDLE ایجاد کنید.	1
Include_doc	نصب راهنمای پایتون	1
Include_debug	نصب دودویی‌های اشکال‌زدایی	0
Include_dev	سرآیندها و کتابخانه‌های توسعه‌دهنده را نصب کنید. صرف‌نظر کردن از این مورد ممکن است به نصبی غیرقابل‌استفاده منجر شود.	1
Include_exe	نصب python.exe و پرونده‌های مرتبط. صرف‌نظر کردن از این مورد ممکن است منجر به نصبی غیرقابل استفاده شود.	1
Include_launcher	مدیر نصب پایتون را نصب کنید.	1
InstallLauncherAllUsers	راه‌انداز را برای همه‌ی کاربران نصب می‌کند. همچنین نیازمند آن است که Include_launcher روی 1 تنظیم شده باشد	1
Include_lib	ماژول‌های کتابخانه استاندارد و ماژول‌های توسعه‌ای را نصب کنید. صرف‌نظر کردن از این مرحله ممکن است به نصبی غیرقابل استفاده منجر شود.	1
Include_pip	نصب pip و setuptools همراه	1
Include_symbols	نصب نمادهای اشکال‌زدایی (*.pdb)	0
Include_tcltk	نصب پشتیبانی Tcl/Tk و IDLE	1
Include_test	نصب بدنه آزمون‌های کتابخانه استاندارد	1
Include_tools	نصب اسکریپت‌های کاربردی	1
LauncherOnly	فقط راه‌انداز را نصب می‌کند. این گزینه بیشتر گزینه‌های دیگر را نادیده می‌گیرد.	0
SimpleInstall	غیرفعال کردن بیشتر رابط کاربری نصب	0
SimpleInstallDescription	پیام سفارشی برای نمایش زمانی که از رابط کاربری نصب ساده‌شده استفاده می‌شود.	(خالی)

برای مثال، برای نصب بی‌صدای پایتون به‌صورت پیش‌فرض و در سطح کل سیستم، می‌توانید از دستور زیر استفاده کنید (از یک خط فرمان با دسترسی مدیر):

python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0

برای اینکه به کاربران اجازه دهید نسخه شخصی پایتون را بدون بدنه آزمون به‌سادگی نصب کنند، می‌توانید میان‌بری با دستور زیر فراهم کنید. این کار صفحه آغازین ساده‌شده‌ای را نمایش می‌دهد و اجازه شخصی‌سازی نمی‌دهد:

python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
    SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."

(توجه داشته باشید که حذف راه‌انداز، تخصیص پرونده‌ها (file associations) را نیز حذف می‌کند و تنها زمانی برای نصب‌های در سطح کاربر توصیه می‌شود که نصب سراسری‌ای که شامل راه‌انداز است نیز وجود داشته باشد.)

گزینه‌های فهرست‌شده در بالا را می‌توان در پرونده‌ای با نام unattend.xml در کنار پرونده اجرایی نیز ارائه کرد. این پرونده فهرستی از گزینه‌ها و مقادیر را مشخص می‌کند. وقتی مقداری به‌صورت ویژگی ارائه شود، در صورت امکان به عدد تبدیل می‌شود. مقادیری که به‌صورت متن عنصر ارائه می‌شوند، همیشه به‌صورت رشته باقی می‌مانند. این پرونده‌ی نمونه همان گزینه‌های مثال قبلی را تنظیم می‌کند:

<Options>
    <Option Name="InstallAllUsers" Value="no" />
    <Option Name="Include_launcher" Value="0" />
    <Option Name="Include_test" Value="no" />
    <Option Name="SimpleInstall" Value="yes" />
    <Option Name="SimpleInstallDescription">فقط برای من، بدون بدنه آزمون‌ها</Option>
</Options>

4.11.4. نصب بدون دانلود

از آنجا که برخی از ویژگی‌های پایتون در دانلود اولیه‌ی نصب‌کننده گنجانده نشده‌اند، انتخاب آن ویژگی‌ها ممکن است نیازمند اتصال به اینترنت باشد. برای جلوگیری از این نیاز، می‌توان همه‌ی اجزای ممکن را به‌صورت درخواستی دانلود کرد تا یک چیدمان (layout) کامل ایجاد شود که صرف‌نظر از ویژگی‌های انتخاب‌شده، دیگر به اتصال به اینترنت نیاز نخواهد داشت. توجه داشته باشید که این دانلود ممکن است بزرگ‌تر از میزان مورد نیاز باشد، اما در مواردی که قرار است تعداد زیادی نصب انجام شود، داشتن یک نسخه‌ی محلی ذخیره‌شده در نهانگاه بسیار مفید است.

برای دانلود تمام پرونده‌های مورد نیاز ممکن، دستور زیر را از طریق خط فرمان (Command Prompt) اجرا کنید. به یاد داشته باشید که python-3.9.0.exe را با نام واقعی نصب‌کننده‌ی خود جایگزین کنید و چیدمان‌ها (layout) را در پوشه‌های اختصاصی خود ایجاد کنید تا از تداخل میان پرونده‌های هم‌نام جلوگیری شود.

python-3.9.0.exe /layout [پوشه مقصد اختیاری]

شما همچنین می‌توانید گزینه‌ی /quiet را برای پنهان کردن نمایش پیشرفت مشخص کنید.

4.11.5. تغییر دادن یک نصب

پس از نصب پایتون، می‌توانید از طریق ابزار «برنامه‌ها و قابلیت‌ها» (Programs and Features) که بخشی از ویندوز است، قابلیت‌هایی را اضافه یا حذف کنید. مورد پایتون را انتخاب کرده و گزینه‌ی «حذف/تغییر» (Uninstall/Change) را برگزینید تا نصاب در حالت نگهداری باز شود.

«Modify» به شما اجازه می‌دهد تا با تغییر کادرهای انتخاب (checkbox)، قابلیت‌ها را اضافه یا حذف کنید؛ کادرهایی که تغییری نکرده‌اند، چیزی را نصب یا حذف نمی‌کنند. برخی گزینه‌ها در این حالت قابل تغییر نیستند، مانند پوشه‌ی نصب؛ برای تغییر این موارد، باید پایتون را به‌طور کامل حذف و سپس دوباره نصب کنید.

گزینه «تعمیر» (Repair) تمام پرونده‌هایی را که باید با استفاده از تنظیمات فعلی نصب شوند بررسی می‌کند و هر کدام را که حذف یا تغییر یافته باشد جایگزین می‌کند.

«Uninstall» پایتون را به‌طور کامل حذف می‌کند، به‌جز مدیر نصب پایتون که مدخل جداگانه‌ای در Programs and Features دارد.

4.11.6. نصب پرونده‌های دودویی نخ‌آزاد

اضافه شده در نسخه‌ی 3.13.

برای نصب پرونده‌های دودویی پیش‌ساخته با نخ‌بندی آزاد فعال (به PEP 703 مراجعه کنید)، باید «Customize installation» را انتخاب کنید. صفحه‌ی دوم گزینه‌ها شامل کادر انتخاب «Download free-threaded binaries» است.

با انتخاب این گزینه، پرونده‌های دودویی اضافی در همان مکان نصب اصلی پایتون بارگیری و نصب می‌شوند. پرونده اجرایی اصلی python3.13t.exe نام دارد و سایر پرونده‌های دودویی یا پسوند t دریافت می‌کنند یا پسوند کامل ABI. پرونده‌های منبع پایتون و وابستگی‌های همراه شخص ثالث، با نصب اصلی به اشتراک گذاشته می‌شوند.

نسخه‌ی نخ‌آزاد به‌عنوان یک نصب معمولی پایتون با برچسب 3.13t ثبت می‌شود (با پسوند -32 یا -arm64، همان‌طور که برای آن پلتفرم‌ها معمول است). این امر به ابزارها امکان می‌دهد آن را کشف کنند و به مدیر نصب پایتون امکان می‌دهد از py.exe -3.13t پشتیبانی کند. توجه داشته باشید که راه‌انداز py.exe -3 (یا یک خط مفسر python3) را به‌عنوان «جدیدترین نصب 3.x» تفسیر می‌کند؛ تفسیری که دودویی‌های نخ‌آزاد را به دودویی‌های معمولی ترجیح می‌دهد، در حالی که py.exe -3.13 چنین نمی‌کند. اگر از سبک کوتاه گزینه استفاده می‌کنید، ممکن است ترجیح دهید در حال حاضر دودویی‌های نخ‌آزاد را نصب نکنید.

برای مشخص کردن گزینه نصب در خط فرمان، از Include_freethreaded=1 استفاده کنید. برای دستورالعمل‌های دانلود پیش‌دستانه‌ی پرونده‌های دودویی اضافی جهت نصب آفلاین، به نصب بدون دانلود مراجعه کنید. گزینه‌های گنجاندن نمادهای اشکال‌زدایی و پرونده‌های دودویی، بر ساخت‌های نخ‌آزاد نیز اعمال می‌شوند.

نسخه‌های دودویی نخ‌آزاد نیز در nuget.org در دسترس هستند.

4.12. راه‌انداز پایتون برای ویندوز (منسوخ)

منسوخ شده از نسخه‌ی 3.14: راه‌انداز و این مستندات توسط مدیر نصب پایتون که در بالا شرح داده شد، جایگزین شده‌اند. این موقتاً به دلیل اهمیت تاریخی حفظ شده است.

اضافه شده در نسخه‌ی 3.3.

راه‌انداز پایتون برای ویندوز ابزاری است که به یافتن و اجرای نسخه‌های مختلف پایتون کمک می‌کند. این ابزار به اسکریپت‌ها (یا خط فرمان) اجازه می‌دهد ترجیح خود را برای یک نسخه‌ی مشخص از پایتون اعلام کنند، و آن نسخه را یافته و اجرا خواهد کرد.

برخلاف متغیر PATH، راه‌انداز مناسب‌ترین نسخه پایتون را به‌درستی انتخاب می‌کند. راه‌انداز نصب‌های در سطح کاربر را به نصب‌های در سطح کل سیستم ترجیح می‌دهد و به‌جای استفاده از جدیدترین نسخه نصب‌شده، بر اساس نسخه زبان ترتیب‌بندی می‌کند.

راه‌انداز در ابتدا در PEP 397 مشخص شده است.

4.12.1. شروع به کار

4.12.1.1. از طریق خط فرمان

تغییر یافته در نسخه‌ی 3.6.

نصب سراسری پایتون 3.3 و نسخه‌های بعدی، راه‌انداز را در PATH شما قرار می‌دهد. راه‌انداز با تمام نسخه‌های موجود پایتون سازگار است، بنابراین مهم نیست کدام نسخه نصب شده است. برای بررسی دسترسی‌پذیری راه‌انداز، دستور زیر را در خط فرمان (Command Prompt) اجرا کنید:

py

خواهید دید که آخرین نسخه‌ای از پایتون که نصب کرده‌اید راه‌اندازی می‌شود - می‌توانید به‌صورت عادی از آن خارج شوید و هر آرگومان خط فرمان اضافه‌ای که مشخص کرده باشید، مستقیماً به پایتون ارسال می‌شود.

اگر چندین نسخه از پایتون نصب کرده‌اید (مثلاً 3.7 و 3.14)، متوجه شده‌اید که پایتون 3.14 اجرا شده است؛ برای راه‌اندازی پایتون 3.7، دستور زیر را امتحان کنید:

py -3.7

اگر می‌خواهید از آخرین نسخه‌ی پایتون 2 که نصب کرده‌اید استفاده کنید، این دستور را امتحان کنید:

py -2

اگر خطای زیر را می‌بینید، راه‌انداز روی سیستم شما نصب نشده است:

'py' به عنوان یک دستور داخلی یا خارجی،
برنامه‌ی قابل اجرا یا پرونده‌ی دسته‌ای شناخته نمی‌شود.

دستور:

py --list

نسخه(های) نصب‌شده‌ی فعلی پایتون را نمایش می‌دهد.

آرگومان -x.y شکل کوتاه آرگومان -V:Company/Tag است که امکان انتخاب یک ران‌تایم مشخص پایتون را فراهم می‌کند، از جمله ران‌تایم‌هایی که ممکن است از جای دیگری غیر از python.org آمده باشند. هر ران‌تایمی که مطابق PEP 514 ثبت شده باشد، قابل کشف خواهد بود. دستور --list همه ران‌تایم‌های دسترس‌پذیر را با استفاده از قالب -V: فهرست می‌کند.

هنگام استفاده از آرگومان -V:، مشخص کردن شرکت (Company) انتخاب را به ران‌تایم‌های آن ارائه‌دهنده محدود می‌کند، در حالی که با مشخص کردن تنها برچسب ، انتخاب از میان همه‌ی ارائه‌دهنده‌ها انجام می‌شود. توجه داشته باشید که حذف اسلش به معنای برچسب است:

# Select any '3.*' tagged runtime
py -V:3

# Select any 'PythonCore' released runtime
py -V:PythonCore/

# Select PythonCore's latest Python 3 runtime
py -V:PythonCore/3

شکل کوتاه آرگومان (-3) تنها از نسخه‌های اصلی پایتون انتخاب می‌کند و نه از توزیع‌های دیگر. با این حال، شکل بلندتر (-V:3) از هر کدام انتخاب خواهد کرد.

شرکت (Company) بر اساس رشته کامل و بدون حساسیت به بزرگی و کوچکی حروف تطبیق داده می‌شود. برچسب یا با رشته کامل یا با پیشوندی تطبیق داده می‌شود، به شرط آنکه نویسه بعدی یک نقطه یا خط تیره باشد. این امر باعث می‌شود -V:3.1 با 3.1-32 تطبیق یابد، اما با 3.10 تطبیق نیابد. برچسب‌ها با استفاده از ترتیب عددی مرتب می‌شوند (3.10 جدیدتر از 3.1 است)، اما با استفاده از متن مقایسه می‌شوند (-V:3.01 با 3.1 تطبیق نمی‌کند).

4.12.1.2. محیط‌های مجازی

اضافه شده در نسخه‌ی 3.5.

اگر راه‌انداز بدون تعیین صریح نسخه پایتون اجرا شود و یک محیط مجازی (ایجادشده با ماژول venv کتابخانه استاندارد یا ابزار خارجی virtualenv) فعال باشد، راه‌انداز به‌جای مفسر سراسری، مفسر محیط مجازی را اجرا می‌کند. برای اجرای مفسر سراسری، یا محیط مجازی را غیرفعال کنید، یا نسخه سراسری پایتون را به‌طور صریح تعیین کنید.

4.12.1.3. از یک اسکریپت

بیایید یک اسکریپت آزمایشی پایتون بسازیم — پرونده‌ای با نام hello.py و با محتوای زیر ایجاد کنید

#! python
import sys
sys.stdout.write("hello from Python %s\n" % (sys.version,))

از پوشه‌ای که hello.py در آن قرار دارد، دستور زیر را اجرا کنید:

py hello.py

باید متوجه شوید که شماره نسخه‌ی جدیدترین نصب پایتون 2.x شما چاپ می‌شود. اکنون سعی کنید سطر اول را به صورت زیر تغییر دهید:

#! python3

اجرای مجدد دستور باید اکنون اطلاعات آخرین نسخه‌ی Python 3.x را چاپ کند. مانند مثال‌های خط فرمان بالا، می‌توانید مشخص‌کننده‌ی صریح‌تری برای نسخه تعیین کنید. با فرض اینکه Python 3.7 را نصب داشته باشید، سطر اول را به #! python3.7 تغییر دهید و باید ببینید که اطلاعات نسخه‌ی 3.7 چاپ می‌شود.

توجه داشته باشید که برخلاف استفاده‌ی تعاملی، «python» خالی از آخرین نسخه‌ی Python 2.x که نصب کرده‌اید استفاده خواهد کرد. این کار برای سازگاری با نسخه‌های پیشین و سازگاری با Unix است، جایی که دستور python معمولاً به Python 2 اشاره می‌کند.

4.12.1.4. از طریق همبستگی پرونده‌ها

راه‌انداز باید هنگام نصب با پرونده‌های پایتون (یعنی پرونده‌های .py، .pyw و .pyc) مرتبط شده باشد. این بدان معناست که وقتی از اکسپلورر ویندوز روی یکی از این پرونده‌ها دوبار کلیک می‌کنید، از راه‌انداز استفاده خواهد شد و در نتیجه می‌توانید از همان امکاناتی که در بالا توضیح داده شد استفاده کنید تا اسکریپت مشخص کند کدام نسخه باید استفاده شود.

مزیت کلیدی این است که یک راه‌انداز واحد می‌تواند بسته به محتویات سطر اول، هم‌زمان از چندین نسخه‌ی پایتون پشتیبانی کند.

4.12.2. سطرهای مفسر

اگر سطر نخست یک پرونده اسکریپت با #! آغاز شود، این سطر به‌عنوان «سطر خط مفسر» شناخته می‌شود. سیستم‌عامل لینوکس و دیگر سیستم‌عامل‌های شبه‌یونیکس به‌طور بومی از چنین سطرهایی پشتیبانی می‌کنند و این سطرها معمولاً در چنین سیستم‌هایی برای مشخص کردن اینکه یک اسکریپت چگونه باید اجرا شود به‌کار می‌روند. این راه‌انداز اجازه می‌دهد از همین امکانات برای اسکریپت‌های پایتون در ویندوز نیز استفاده شود و مثال‌های بالا نحوه استفاده از آن‌ها را نشان می‌دهند.

برای اینکه سطرهای مفسر در اسکریپت‌های پایتون بین یونیکس و ویندوز قابل حمل باشند، این راه‌انداز از تعدادی دستور «مجازی» برای تعیین اینکه از کدام مفسر استفاده شود، پشتیبانی می‌کند. دستورهای مجازی پشتیبانی‌شده عبارت‌اند از:

• /usr/bin/env

• /usr/bin/python

• /usr/local/bin/python

• python

برای مثال، اگر سطر اول اسکریپت شما شروع شود با

#! /usr/bin/python

پایتون پیش‌فرض یا یک محیط مجازی فعال یافته و مورد استفاده قرار می‌گیرد. از آنجا که بسیاری از اسکریپت‌های پایتون که برای کار روی یونیکس نوشته شده‌اند، از قبل این سطر را دارند، خواهید دید که این اسکریپت‌ها بدون تغییر توسط راه‌انداز قابل استفاده هستند. اگر در ویندوز اسکریپت جدیدی می‌نویسید که امیدوارید روی یونیکس مفید باشد، باید از یکی از سطرهای خط مفسر که با /usr شروع می‌شوند استفاده کنید.

هر یک از فرمان‌های مجازی بالا می‌تواند نسخه‌ای صریح را به‌عنوان پسوند بگیرد (فقط نسخه‌ی اصلی، یا هر دو نسخه‌ی اصلی و فرعی). افزون بر این، می‌توان نسخه‌ی ۳۲‌بیتی را با افزودن "-32" پس از نسخه‌ی فرعی درخواست کرد. یعنی /usr/bin/python3.7-32 استفاده از نسخه‌ی ۳۲‌بیتی پایتون 3.7 را درخواست خواهد کرد. اگر یک محیط مجازی فعال باشد، نسخه نادیده گرفته می‌شود و از محیط استفاده خواهد شد.

اضافه شده در نسخه‌ی 3.7: از راه‌انداز پایتون 3.7 به بعد، می‌توان با پسوند "-64" نسخه‌ی ۶۴ بیتی را درخواست کرد. علاوه بر این، می‌توان شماره‌ی اصلی و معماری را بدون شماره‌ی فرعی مشخص کرد (یعنی /usr/bin/python3-64).

تغییر یافته در نسخه‌ی 3.11: پسوند «-64» منسوخ شده است و اکنون به معنای «هر معماری که i386/32-bit بودن آن قابل اثبات نباشد» است. برای درخواست یک محیط مشخص، از آرگومان جدید -V:TAG همراه با تگ کامل استفاده کنید.

تغییر یافته در نسخه‌ی 3.13: فرمان‌های مجازی ارجاع‌دهنده به python اکنون به‌جای جستجو در PATH محیط مجازی فعال را ترجیح می‌دهند. این، مواردی را مدیریت می‌کند که در آن‌ها خط مفسر /usr/bin/env python3 را مشخص می‌کند، اما python3.exe در محیط فعال موجود نیست.

شکل /usr/bin/env از سطر خط مفسر یک ویژگی خاص دیگر نیز دارد. پیش از جستجوی مفسرهای نصب‌شده پایتون، این شکل مسیر اجرایی PATH را برای یافتن یک پرونده اجرایی پایتون که با نام ارائه‌شده به‌عنوان آرگومان اول مطابقت دارد، جستجو می‌کند. این با رفتار برنامه env یونیکس مطابقت دارد که یک جستجوی PATH انجام می‌دهد. اگر پرونده اجرایی‌ای که با آرگومان اول پس از دستور env مطابقت دارد یافت نشود، اما آرگومان با python آغاز شود، به همان شکلی که برای سایر دستورهای مجازی توضیح داده شد، مدیریت خواهد شد. متغیر محیطی PYLAUNCHER_NO_SEARCH_PATH می‌تواند (به هر مقداری) تنظیم شود تا از این جستجوی PATH صرف‌نظر شود.

سطرهای مفسر که با هیچ‌یک از این الگوها مطابقت ندارند، در بخش [commands] از پرونده‌ی .INI راه‌انداز جستجو می‌شوند. می‌توان از این امکان برای رسیدگی به برخی دستورها به شکلی که برای سیستم شما منطقی باشد استفاده کرد. نام دستور باید یک آرگومان تکی باشد (بدون فاصله در پرونده‌ی اجراییِ خط مفسر)، و مقداری که جایگزین می‌شود، مسیر کامل پرونده‌ی اجرایی است (آرگومان‌های اضافی که در .INI مشخص شده‌اند، به‌عنوان بخشی از نام پرونده داخل گیومه قرار می‌گیرند).

[commands]
/bin/xpython=C:\Program Files\XPython\python.exe

هر دستوری که در پرونده‌ی .INI یافت نشود، به‌عنوان مسیرهای اجرایی ویندوز در نظر گرفته می‌شود که مطلق‌اند یا نسبت به پوشه‌ی حاوی پرونده‌ی اسکریپت هستند. این امکان برای راحتی اسکریپت‌های مخصوص ویندوز، مانند اسکریپت‌هایی که توسط یک نصب‌کننده تولید می‌شوند، فراهم شده است، زیرا این رفتار با پوسته‌های سبک یونیکس سازگار نیست. این مسیرها می‌توانند داخل علامت نقل‌قول قرار بگیرند و می‌توانند شامل چندین آرگومان باشند؛ پس از آن‌ها، مسیر اسکریپت و هر آرگومان اضافی به آن‌ها الحاق خواهد شد.

4.12.3. آرگومان‌ها در سطرهای مفسر

سطرهای مفسر همچنین می‌توانند گزینه‌های اضافی‌ای را مشخص کنند که به مفسر پایتون پاس داده می‌شوند. برای مثال، اگر یک خط مفسر داشته باشید:

#! /usr/bin/python -v

سپس پایتون با گزینه‌ی -v اجرا خواهد شد

4.12.4. سفارشی‌سازی

4.12.4.1. سفارشی‌سازی از طریق پرونده‌های INI

دو پرونده‌ی .ini توسط راه‌انداز جستجو می‌شوند — py.ini در پوشه‌ی داده‌های برنامه‌ی کاربر فعلی (%LOCALAPPDATA% یا $env:LocalAppData) و py.ini در همان پوشه‌ای که راه‌انداز در آن قرار دارد. همین پرونده‌های .ini هم برای نسخه‌ی «کنسول» راه‌انداز (یعنی py.exe) و هم برای نسخه‌ی «ویندوز» (یعنی pyw.exe) استفاده می‌شوند.

سفارشی‌سازی مشخص‌شده در «پوشه برنامه» بر سفارشی‌سازی موجود در کنار پرونده اجرایی تقدم دارد؛ بنابراین کاربری که ممکن است دسترسی نوشتن به پرونده .ini کنار راه‌انداز را نداشته باشد، می‌تواند دستورهای آن پرونده .ini سراسری را بازنویسی کند.

4.12.4.2. سفارشی‌سازی نسخه‌های پیش‌فرض پایتون

در برخی موارد، می‌توان یک مشخص‌کننده نسخه را در یک فرمان گنجاند تا تعیین کند که کدام نسخه پایتون توسط آن فرمان استفاده خواهد شد. مشخص‌کننده نسخه با یک شماره نسخه اصلی آغاز می‌شود و می‌تواند به‌صورت اختیاری با یک نقطه ('.') و یک مشخص‌گر نسخه فرعی ادامه یابد. علاوه بر این، می‌توان با افزودن "-32" یا "-64" مشخص کرد که پیاده‌سازی ۳۲ یا ۶۴ بیتی درخواست شود.

برای مثال، خط مفسر #!python هیچ مشخص‌کننده‌ی نسخه‌ای ندارد، در حالی که #!python3 مشخص‌کننده‌ی نسخه‌ای دارد که تنها یک نسخه‌ی اصلی را مشخص می‌کند.

اگر در یک دستور هیچ مشخص‌کننده نسخه‌ای یافت نشود، می‌توان متغیر محیطی PY_PYTHON را برای تعیین مشخص‌کننده نسخه پیش‌فرض تنظیم کرد. اگر تنظیم نشده باشد، پیش‌فرض "3" است. این متغیر می‌تواند هر مقداری را تعیین کند که بتوان آن را در خط فرمان پاس داد، مانند "3"، "3.7"، "3.7-32" یا "3.7-64". (توجه داشته باشید که گزینه "-64" تنها با راه‌انداز همراه پایتون 3.7 یا جدیدتر در دسترس است.)

اگر هیچ مشخص‌کننده‌ی نسخه‌ی جزئی یافت نشود، می‌توان متغیر محیطی PY_PYTHON{major} (که در آن {major} مشخص‌کننده‌ی نسخه‌ی اصلی فعلی است، همان‌طور که در بالا تعیین شد) را برای مشخص کردن نسخه‌ی کامل تنظیم کرد. اگر چنین گزینه‌ای یافت نشود، راه‌انداز نسخه‌های نصب‌شده‌ی پایتون را برمی‌شمارد و از جدیدترین نسخه‌ی جزئی یافت‌شده برای آن نسخه‌ی اصلی استفاده می‌کند که به احتمال زیاد، هرچند تضمین‌شده نیست، آخرین نسخه‌ی نصب‌شده در آن خانواده است.

در ویندوز ۶۴بیتی که هر دو پیاده‌سازی ۳۲بیتی و ۶۴بیتی از نسخه یکسان (major.minor) پایتون در آن نصب شده باشند، همیشه نسخه ۶۴بیتی ترجیح داده می‌شود. این برای هر دو پیاده‌سازی ۳۲بیتی و ۶۴بیتی راه‌انداز برقرار است — راه‌انداز ۳۲بیتی در صورت وجود ترجیح می‌دهد نصب ۶۴بیتی پایتون از نسخه مشخص‌شده را اجرا کند. دلیل این امر آن است که رفتار راه‌انداز بتواند صرفاً با دانستن اینکه چه نسخه‌هایی روی رایانه نصب شده‌اند و بدون توجه به ترتیبی که در آن نصب شده‌اند پیش‌بینی شود (یعنی بدون دانستن اینکه آخرین بار نسخه ۳۲ یا ۶۴بیتی پایتون و راه‌انداز متناظر آن نصب شده است). همان‌طور که در بالا ذکر شد، می‌توان از پسوند اختیاری «-32» یا «-64» روی مشخص‌کننده نسخه استفاده کرد تا این رفتار تغییر کند.

مثال‌ها:

• اگر هیچ‌یک از گزینه‌های مرتبط تنظیم نشده باشند، دستورات python و python2 از جدیدترین نسخه‌ی نصب‌شده‌ی پایتون 2.x استفاده خواهند کرد و دستور python3 از جدیدترین نسخه‌ی نصب‌شده‌ی پایتون 3.x استفاده خواهد کرد.

• دستور python3.7 هیچ گزینه‌ای را به هیچ وجه بررسی نخواهد کرد، زیرا نسخه‌ها به‌طور کامل مشخص شده‌اند.

• اگر PY_PYTHON=3 باشد، هر دو دستور python و python3 از آخرین نسخه‌ی نصب‌شده‌ی پایتون ۳ استفاده خواهند کرد.

• اگر PY_PYTHON=3.7-32 باشد، دستور python از پیاده‌سازی ۳۲-بیتی نسخه‌ی 3.7 استفاده خواهد کرد، در حالی که دستور python3 از جدیدترین پایتون نصب‌شده استفاده خواهد کرد (PY_PYTHON به‌هیچ‌وجه در نظر گرفته نشد، زیرا یک نسخه‌ی اصلی مشخص شده بود.)

• اگر PY_PYTHON=3 و PY_PYTHON3=3.7 باشند، فرمان‌های python و python3 هر دو دقیقاً از نسخه 3.7 استفاده خواهند کرد

علاوه بر متغیرهای محیطی، همین تنظیمات را می‌توان در پرونده‌ی .INI که راه‌انداز از آن استفاده می‌کند نیز پیکربندی کرد. بخش مربوطه در پرونده‌ی INI [defaults] نام دارد و نام کلید، همان نام متغیرهای محیطی بدون پیشوند PY_ خواهد بود (و توجه داشته باشید که نام کلیدها در پرونده‌ی INI به بزرگی و کوچکی حروف حساس نیستند.) محتوای متغیر محیطی، موارد تعیین‌شده در پرونده‌ی INI را بازنویسی می‌کند.

برای مثال:

• تنظیم کردن PY_PYTHON=3.7 معادل پرونده‌ی INI است که حاوی:

[defaults]
python=3.7

• تنظیم PY_PYTHON=3 و PY_PYTHON3=3.7 معادل پرونده‌ی INI حاوی موارد زیر است:

[defaults]
python=3
python3=3.7

4.12.5. عیب‌یابی

اگر متغیر محیطی PYLAUNCHER_DEBUG تنظیم شده باشد (به هر مقداری)، راه‌انداز اطلاعات تشخیصی را به stderr چاپ می‌کند (یعنی به کنسول). با اینکه این اطلاعات هم‌زمان پرگوی و موجز است، باید به شما امکان دهد ببینید چه نسخه‌هایی از پایتون یافت شده‌اند، چرا نسخه‌ی خاصی انتخاب شده است و خط فرمان دقیق مورد استفاده برای اجرای پایتون هدف چیست. این اطلاعات عمدتاً برای آزمون و اشکال‌زدایی در نظر گرفته شده است.

4.12.6. اجرای آزمایشی (dry run)

اگر متغیر محیطی PYLAUNCHER_DRYRUN تنظیم شده باشد (به هر مقداری)، راه‌انداز دستوری را که قرار بود اجرا کند در خروجی نمایش می‌دهد، اما در واقعیت پایتون را راه‌اندازی نمی‌کند. این ممکن است برای ابزارهایی که می‌خواهند از راه‌انداز برای تشخیص و سپس راه‌اندازی مستقیم پایتون استفاده کنند مفید باشد. توجه داشته باشید که دستوری که در خروجی استاندارد نوشته می‌شود، همیشه با استفاده از UTF-8 کدگذاری می‌شود و ممکن است در کنسول به‌درستی نمایش داده نشود.

4.12.7. نصب در صورت نیاز

اگر متغیر محیطی PYLAUNCHER_ALLOW_INSTALL تنظیم‌شده باشد (به هر مقداری)، و نسخه‌ی درخواستی پایتون نصب‌نشده باشد اما در Microsoft Store موجود باشد، راه‌انداز تلاش خواهد کرد آن را نصب کند. این کار ممکن است برای تکمیل به تعامل کاربر نیاز داشته باشد، و ممکن است لازم باشد دستور را دوباره اجرا کنید.

متغیر اضافی PYLAUNCHER_ALWAYS_INSTALL باعث می‌شود راه‌انداز همیشه سعی کند پایتون را نصب کند، حتی اگر پایتون شناسایی شده باشد. این عمدتاً برای آزمون در نظر گرفته شده است (و باید همراه با PYLAUNCHER_DRYRUN استفاده شود).

4.12.8. کدهای بازگشتی

کدهای خروج زیر ممکن است توسط راه‌انداز پایتون برگردانده شوند. متأسفانه، هیچ راهی برای تشخیص این کدها از کد خروج خودِ پایتون وجود ندارد.

نام‌های کدها همان‌گونه‌اند که در منابع به کار رفته‌اند و صرفاً جنبه‌ی مرجع دارند. هیچ راهی برای دسترسی یا حل آن‌ها به‌جز خواندن این صفحه وجود ندارد. ورودی‌ها به ترتیب الفبایی نام‌ها فهرست شده‌اند.

نام	مقدار	توضیحات
RC_BAD_VENV_CFG	107	پرونده pyvenv.cfg یافت شد، اما خراب است.
RC_CREATE_PROCESS	101	راه‌اندازی پایتون ناموفق بود.
RC_INSTALLING	111	یک نصب آغاز شد، اما فرمان باید پس از اتمام آن دوباره اجرا شود.
RC_INTERNAL_ERROR	109	خطای غیرمنتظره. لطفاً این اشکال را گزارش کنید.
RC_NO_COMMANDLINE	108	امکان دریافت خط فرمان از سیستم‌عامل وجود ندارد.
RC_NO_PYTHON	103	امکان یافتن نسخه‌ی درخواستی وجود ندارد.
RC_NO_VENV_CFG	106	پرونده pyvenv.cfg لازم بود، اما یافت نشد.