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

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

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

To obtain Python from the CPython team, use the Python install manager. This is a standalone tool that makes Python available as global commands on your Windows machine, integrates with the system, and supports updates over time. You can download the Python install manager from python.org/downloads or through the Microsoft Store app.

Once you have installed the Python install manager, the global python command can be used from any terminal to launch your current latest version of Python. This version may change over time as you add or remove different versions, and the py list command will show which is current.

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

If the python or py commands do not seem to be working, see the Troubleshooting section below. There are sometimes additional manual steps required to configure your PC.

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

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

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

4.1.1. نصب

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

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

To install the file downloaded from python.org, either double-click and select "Install", or run Add-AppxPackage <path to MSIX> in Windows PowerShell.

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

When you first install a runtime, you will likely be prompted to add a directory to your PATH. This is optional, if you prefer to use the py command, but is offered for those who prefer the full range of aliases (such as python3.16.exe) to be available. The directory will be %LocalAppData%\Python\bin by default, but may be customized by an administrator. Click Start and search for "Edit environment variables for your account" for the system settings page to add the path.

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

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

If you are not able to install an MSIX in your context, for example, you are using automated deployment software that does not support it, or are targeting Windows Server 2019, see نصب پیشرفته below for more information.

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

A range of formats are supported, and can be passed as the --format=<FMT> or -f <FMT> option. Formats include table (a user-friendly table view), csv (comma-separated table), json (a single JSON blob), jsonl (one JSON blob per result), exe (just the executable path), prefix (just the prefix path).

گزینه‌ی --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.16

For compatibility with the old launcher, the --list, --list-paths, -0 and -0p commands (for example, py -0p) are retained. They do not allow additional options, and will produce legacy-formatted output.

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

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

py install PythonTest\3.16

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

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

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

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

Passing --refresh will update all registrations for installed runtimes. This will recreate Start menu shortcuts, registry keys, and global aliases (such as python3.16.exe or for any installed scripts). These are automatically refreshed on installation of any runtime, but may need to be manually refreshed after installing packages.

علاوه بر گزینه‌های بالا، گزینه‌ی --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

The preferred default platform to launch or install. This is treated as a suffix to the specified tag, such that py -V:3.16 would prefer an install for 3.16-64 if it exists (and default_platform is -64), but will use 3.16 if no tagged install exists.

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

(هیچ)

Specify the directory where global commands (such as python3.16.exe and pip.exe) are stored. This directory should be added to your PATH to make the commands available from your terminal.

download_dir

(هیچ)

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

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

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

If the first line of a script file starts with #!, it is known as a "shebang" line. Linux and other Unix-like operating systems have native support for such lines and they are commonly used on such systems to indicate how a script should be executed. The python and py commands allow the same facilities to be used with Python scripts on Windows.

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

  • /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 lines that do not match any of the patterns are treated as Windows executable paths that are absolute or relative to the directory containing the script file. This is a convenience for Windows-only scripts, such as those generated by an installer, since the behavior is not compatible with Unix-style shells. These paths may be quoted, and may include multiple arguments, after which the path to the script and any additional arguments will be appended. This functionality may be disabled by the shebang_can_run_anything configuration option.

از نسخه 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 ویندوز، یا مستندات و پشتیبانی ابزار استقرار خود را بررسی کنید.

Regardless of the install method, users will still need to install their own copies of Python itself, as there is no way to trigger those installs without being a logged-in user. When using the MSIX, the latest version of Python will be available for all users to install without network access.

توجه داشته باشید که بسته‌های 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

Comma-separated list of shortcut kinds to allow (for example, "pep514,start"). Enabled shortcuts may still be disabled by disable_shortcut_kinds.

install.disable_shortcut_kinds

Comma-separated list of shortcut kinds to exclude (for example, "pep514,start"). Disabled shortcuts are not reactivated by 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.16t
$> py install 3.16t-arm64
$> py install 3.16t-32

This will install and register as normal. If you have no other runtimes installed, then python will launch this one. Otherwise, you will need to use py -V:3.16t or, if you have added the global aliases directory to your PATH environment variable, the python3.16t.exe commands.

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

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

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

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

As well as requiring a valid signature, the required_root_subject and required_publisher_subject settings can further restrict acceptable signatures based on the certificate Subject fields. Any attribute specified in the configuration must match the attribute in the certificate (additional attributes in the certificate are ignored). Typical attributes are CN= for the common name, O= for the organization, and C= for the publisher's country.

در نهایت، تنظیم 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. تنظیمات پراکسی

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

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

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

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

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

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

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

4.1.15. عیب‌یابی

If your Python install manager does not seem to be working correctly, work through these tests and fixes to see if it helps. If not, report an issue at our bug tracker, including any relevant log files (written to your %TEMP% directory by default).

عیب‌یابی

نشانه

کارهایی برای امتحان کردن

وقتی 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.16-embed --target=<directory>

When extracted, the embedded distribution is (almost) fully isolated from the user's system, including environment variables, system registry settings, and installed packages. The standard library is included as pre-compiled and optimized .pyc files in a ZIP, and python3.dll, python316.dll, python.exe and pythonw.exe are all provided. Tcl/Tk (including all dependents, such as IDLE), pip and the Python documentation are not included.

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

As with the application use, packages can be installed to any location as there is an opportunity to specify search paths before initializing the interpreter. Otherwise, there are no fundamental differences between using the embedded distribution and a regular installation.

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

Alongside the tools directory is a build\native directory. This contains an MSBuild properties file python.props that can be used in a C++ project to reference the Python install. Including the settings will automatically use the headers and import libraries in your build.

The package information pages on nuget.org are www.nuget.org/packages/python for the 64-bit version, www.nuget.org/packages/pythonx86 for the 32-bit version, and www.nuget.org/packages/pythonarm64 for the ARM64 version.

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.

Packages containing free-threaded binaries are named python-freethreaded for the 64-bit version, pythonx86-freethreaded for the 32-bit version, and pythonarm64-freethreaded for the ARM64 version. These packages contain both the python3.16t.exe and python.exe entry points, both of which run free-threaded.

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

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

ActivePython

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

Anaconda

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

Enthought Deployment Manager

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

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

WinPython

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

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

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

As specified in PEP 11, a Python release only supports a Windows platform while Microsoft considers the platform under extended support. This means that Python 3.16 supports Windows 10 and newer. If you require Windows 7 support, install Python 3.8. If you require Windows 8.1 support, install Python 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: حالت UTF-8 پایتون اکنون به‌طور پیش‌فرض فعال است (PEP 686).

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

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

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

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

راهنمایی

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

نکته

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

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

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

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

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

  • If the environment variable PYTHONPATH exists, as described in متغیرهای محیطی, its entries are added next. Note that on Windows, paths in this variable must be separated by semicolons, to distinguish them from the colon used in drive identifiers (such as C:\).

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

  • If the environment variable PYTHONHOME is set, it is assumed as "Python Home". Otherwise, the path of the main Python executable is used to locate a "landmark file" (either Lib\os.py or pythonXY.zip) to deduce the "Python Home". If a Python home is found, the relevant sub-directories added to sys.path (such as Lib and plat-win) are based on that folder. Otherwise, the core Python path is constructed from the PythonPath stored in the registry.

  • If the Python Home cannot be located, no PYTHONPATH is specified in the environment, and no registry entries can be found, a default path with relative entries is used (for example, .\Lib;.\plat-win).

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

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

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

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

  • When Python is hosted in another .exe (for example, in a different directory or embedded via COM), the "Python Home" will not be deduced, so the core path from the registry is used. Other "application paths" in the registry are always read.

  • If Python can't find its home and there are no registry values (frozen .exe, some very strange installation setup) you get a path with some default, but relative, paths.

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

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

  • If you are loading python3.dll or python316.dll in your own executable, explicitly set PyConfig.module_search_paths before Py_InitializeFromConfig().

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

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

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

تغییر یافته در نسخه‌ی 3.6: Add ._pth file support and remove applocal option from 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 در ویندوز مراجعه کنید.