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

Resolve error Unable to find package 'python' from a misconfigured nuget.config using:

nuget.exe sources add -Name "nuget.org" -source "https://api.nuget.org/v3/index.json"

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.16 از ویندوز 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.

تغییر یافته در نسخه‌ی 3.15: Python UTF-8 mode is now enabled by default (PEP 686).

Windows still uses legacy encodings for the system encoding (the ANSI Code Page). When the Python UTF-8 Mode is disabled, Python uses the ANSI Code Page as the default encoding of text files, as returned by locale.getencoding().

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

The Python UTF-8 Mode, enabled by default, ignores the system encoding and uses UTF-8 as the default text encoding. When the UTF-8 mode is enabled, you can still use the system encoding (the ANSI Code Page) via the "mbcs" codec.

You can disable the Python UTF-8 Mode via the -X utf8=0 command line option, or the PYTHONUTF8=0 environment variable. See PYTHONUTF8 for disabling UTF-8 mode, and مدیر نصب پایتون for how to modify environment variables.

راهنمایی

Adding PYTHONUTF8={0,1} to the default environment variables will affect all Python 3.7+ applications on your system. If you have any Python 3.7+ applications which rely on the legacy system encoding, it is recommended to set the environment variable temporarily or use the -X utf8 command line option.

توجه

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

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

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 در ویندوز مراجعه کنید.