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 برای انتخاب نسخه‌ی پیش‌فرض استفاده کرد. محدوده‌ها برای نصب پشتیبانی نمی‌شوند.

CPython publishes multiple runtime variants. For most users, PythonCore is recommended and provides the standard CPython runtime. Tags without any prefix are treated as PythonCore\<TAG>.

PythonTest includes the standard runtime together with the test suite and debugging symbols. It is intended for contributors or users who need these additional files for testing or debugging Python.

PythonEmbed provides a minimal embeddable distribution for applications that bundle Python rather than for interactive use. It would normally be used with the --target option described below.

To see the available runtime variants, run:

$> py list --online 3.14

To install a specific variant, include it in the tag passed to py install:

py install PythonTest\3.15

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

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

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

با ارسال --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 (اما نه هر دو) مشخص شود. این مکان‌ها ممکن است با گزینه‌های سفارشی‌سازی مدیریتی که در ادامه فهرست شده‌اند، اصلاح شوند.

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

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

نام‌های نقطه‌دار باید درون اشیاء 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 نباشد، در خط مفسر بازنویسی می‌شود و پردازش عادی ادامه می‌یابد. اگر اجرای پرونده‌های اجرایی دلخواه مجاز باشد، با مشخص کردن مسیر کامل می‌توانید از پایتون به هر پرونده اجرایی تغییر مسیر دهید. الگو باید یا تمام سطر را (با نادیده گرفتن فاصله‌های ابتدایی و انتهایی) تطبیق دهد، یا تا اولین فاصله در خط مفسر.

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

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

آگاه باشید که بسته‌ی 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% بازنویسی کنید، به‌جای آن از این متغیر محیطی استفاده خواهد شد.

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

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

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

توزیع‌های از پیش ساخته‌شده‌ی ساخت‌ نخ‌آزاد با نصب تگ‌های دارای پسوند 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. امضاهای اندیس¶

پرونده‌های اندیس را می‌توان برای تشخیص دستکاری امضا کرد. امضا، پرونده کاتالوگی در همان 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. تنظیمات پراکسی¶

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

برای نادیده گرفتن تنظیمات، از متغیرهای محیطی NO_PROXY، HTTP_PROXY و HTTPS_PROXY استفاده کنید. این متغیرها باید در نشست ترمینال قبل از استفاده از مدیر نصب پایتون تنظیم شوند. سایر برنامه‌ها نیز ممکن است از این متغیرها استفاده کنند، بنابراین قبل از تنظیم آن‌ها به صورت سراسری برای کل دستگاه‌تان احتیاط کنید.

تنظیم NO_PROXY روی هر مقدار غیرخالی، استفاده از هر پراکسی را غیرفعال می‌کند. از این برای دور زدن تنظیم پیش‌فرض پراکسی سیستم و تلاش برای دسترسی مستقیم به سرور اندیس استفاده کنید.

تنظیم HTTPS_PROXY روی رشته‌ای مانند example.com:8080 باعث اتصال به آن سرور پراکسی برای تمام اتصالات HTTPS می‌شود. برای اندیس پیش‌فرض، تمام اتصالات از HTTPS استفاده می‌کنند، بنابراین این تنظیم معمول برای بازنویسی است.

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

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

4.1.15. عیب‌یابی¶

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

عیب‌یابی

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

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

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

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

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

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

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

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

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

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

4.9.1. PyWin32¶

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

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

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

• رجیستری

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

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

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

4.9.2. cx_Freeze¶

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

4.11.1. مراحل نصب¶

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

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

اگر «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 و بیشتر سایر قابلیت‌های مسیر اجازه می‌دهد تا مسیرهای بلندتر از ۲۶۰ نویسه را بپذیرند و بازگردانند.

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

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

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

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

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

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

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. نصب پرونده‌های دودویی نخ‌آزاد¶

برای نصب پرونده‌های دودویی پیش‌ساخته با نخ‌بندی آزاد فعال (به 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.1. شروع به کار¶

py

py -3.7

py -2

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

py --list

# 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

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

py hello.py

#! python3

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 را درخواست خواهد کرد. اگر یک محیط مجازی فعال باشد، نسخه نادیده گرفته می‌شود و از محیط استفاده خواهد شد.

شکل /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. سفارشی‌سازی¶

[defaults]
python=3.7

[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. کدهای بازگشتی¶

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

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