--- title: "خطای ⁦externally-managed-environment⁩ در pip و راه رفع آن" description: "خطای externally-managed-environment یعنی سیستم‌عامل این Python را مدیریت می‌کند و pip در آن نصب نمی‌کند. از venv، pipx یا بسته توزیع استفاده کنید." url: https://proxynet.io/fa/blog/externally-managed-environment date: 2026-10-11 author: "Acar Diveroli" category: "آموزش‌ها" lang: fa --- # خطای ⁦externally-managed-environment⁩ در pip و راه رفع آن یک سرور تازه ⁦Ubuntu 24.04⁩، یک Raspberry Pi یا یک مک با Homebrew راه‌اندازی می‌کنید، مثل سال‌های گذشته `pip install requests` را تایپ می‌کنید و pip با `error: externally-managed-environment` متوقف می‌شود. همان فرمان روی دستگاه قدیمی‌تان هنوز کار می‌کند و پیام از شما می‌خواهد به‌جای آن از `apt`، یک محیط مجازی یا `pipx` استفاده کنید. این راهنما توضیح می‌دهد این خطا از چه چیزی محافظت می‌کند و کدام سیستم‌ها آن را فعال می‌کنند، و راه‌حل‌ها را به ترتیبی که توصیه می‌کنیم می‌آورد؛ پرچمی که این محافظت را کنار می‌گذارد در آخر می‌آید. همه فرمان‌ها را روی یک بازتولید از این خطا اجرا کردیم. بخش‌های پایانی به pip پشت سرور پروکسی و نخستین درخواست از طریق پروکسی از محیط تازه می‌پردازند. > **نکته: پاسخ کوتاه** > > سیستم‌عامل شما Python خود را تحت مدیریت مدیر بسته خودش علامت‌گذاری کرده است (⁦PEP 668⁩): فایلی به نام `EXTERNALLY-MANAGED` در پوشه کتابخانه استاندارد قرار دارد و ⁦pip 23.0⁩ و نسخه‌های بعدی از نصب یا حذف بسته در آنجا خودداری می‌کنند، نصب‌های `--user` هم شامل این قاعده‌اند. برای پروژه یک محیط مجازی بسازید (`python3 -m venv .venv`، سپس `.venv/bin/python -m pip install …`)، برای ابزارهای خط فرمان از `pipx` استفاده کنید یا بسته خود توزیع را نصب کنید (`sudo apt install python3-requests`). `--break-system-packages` این بررسی را خاموش می‌کند، اما در آن صورت pip می‌تواند کتابخانه‌هایی را جایگزین کند که سیستم شما به آن‌ها وابسته است. ## پیام ⁦error: externally-managed-environment⁩ یعنی چه؟ یعنی pip نشانگری پیدا کرده که می‌گوید ابزار دیگری صاحب این نصب Python است. [⁦PEP 668⁩](https://peps.python.org/pep-0668/) این نشانگر را تعریف می‌کند: فایلی به نام `EXTERNALLY-MANAGED` در پوشه کتابخانه استاندارد مفسر، برای نمونه `/usr/lib/python3.13/` در ⁦Debian 13⁩. pip از نسخه 23.0، که در ژانویه 2023 منتشر شد، این فایل را می‌خواند. وقتی فایل وجود دارد و pip درون یک محیط مجازی اجرا نمی‌شود، متن فایل را چاپ می‌کند و بدون نصب هیچ چیزی خارج می‌شود. خطا را روی ویندوز 11 با ⁦pip 26.2.1⁩ بازتولید کردیم: متن نشانگر ⁦Debian 13⁩ را در پوشه کتابخانه استاندارد یک ⁦Python 3.14.8⁩ موقت و دورریختنی گذاشتیم و `python -m pip install requests` را اجرا کردیم. خروجی با آنچه کاربران Debian می‌بینند یکی است: ```text error: externally-managed-environment × This environment is externally managed ╰─> To install Python packages system-wide, try apt install python3-xyz, where xyz is the package you are trying to install. If you wish to install a non-Debian-packaged Python package, create a virtual environment using python3 -m venv path/to/venv. Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make sure you have python3-full installed. If you wish to install a non-Debian packaged Python application, it may be easiest to use pipx install xyz, which will manage a virtual environment for you. Make sure you have pipx installed. See /usr/share/doc/python3.13/README.venv for more information. note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages. hint: See PEP 668 for the detailed specification. ``` دو سطر نخست و سطرهای `note` و `hint` از خود pip می‌آیند. بلوک تورفته متن فایل نشانگر است، پس با سیستم تغییر می‌کند: Arch Linux فرمان `pacman -S python-xyz` و Homebrew فرمان `brew install xyz` را پیشنهاد می‌دهد و هر دو به محیط مجازی و pipx هم اشاره می‌کنند. ## چرا pip از نصب در اینجا خودداری می‌کند؟ چون در غیر این صورت دو مدیر بسته، بی‌خبر از یکدیگر، در یک پوشه می‌نوشتند. در Debian، Ubuntu یا Arch بخش‌هایی از سیستم‌عامل با Python نوشته شده‌اند و کتابخانه‌هایی را وارد (import) می‌کنند که مدیر بسته سیستم نصب کرده است. آن مدیر بسته ثبت می‌کند این برنامه‌ها به کدام نسخه‌ها نیاز دارند؛ pip این سوابق را نمی‌خواند. ⁦PEP 668⁩ پیامد را شرح می‌دهد: یک `pip install` می‌تواند کتابخانه‌ای را که همراه سیستم‌عامل آمده ارتقا دهد یا حذف کند و حتی مدیر بسته خود Fedora، یعنی `dnf`، را از کار بیندازد. فرستادن pip به پوشه‌ای جداگانه هم این مشکل را حل نمی‌کند. توزیع‌ها بسته‌هایی را که به‌صورت محلی نصب می‌شوند در جاهایی مانند `/usr/local` می‌گذارند و در چیدمانی که ⁦PEP 668⁩ توصیه می‌کند، نصب‌های محلی بر بسته‌های توزیع مقدم‌اند، پس برنامه‌های Python سیستم هر چیزی را که pip آنجا گذاشته وارد می‌کنند. نشانگر تکلیف را روشن می‌کند: پروژه‌ها محیط‌های خودشان را می‌گیرند و Python سیستم همان‌طور که توزیع ساخته است باقی می‌ماند. ## pip چگونه تصمیم می‌گیرد نصبی را مسدود کند؟ 1. **بررسی می‌کند که درون محیط مجازی است یا نه.** درون یک venv، مقدار `sys.prefix` با `sys.base_prefix` فرق دارد، بررسی همان‌جا تمام می‌شود و نصب انجام می‌شود. 2. **دنبال نشانگر می‌گردد**، در پوشه‌ای که `sysconfig.get_path("stdlib")` برمی‌گرداند. 3. **پیام را می‌خواند**، از کلید `Error` فایل یا، اگر فایل کلید ترجمه‌شده `Error-` داشته باشد، از آن کلید، و آن را چاپ می‌کند. 4. **هم `pip install` و هم `pip uninstall` را مسدود می‌کند.** `--user` کمکی نمی‌کند: در آزمون ما `pip install --user requests` با همان خطا متوقف شد. اجرای pip با `sudo` هم چیزی را تغییر نمی‌دهد. 5. **گزینه `--break-system-packages` این بررسی را کنار می‌گذارد**، و شکل‌های متغیر محیطی و فایل پیکربندی آن هم همین کار را می‌کنند که در ادامه آمده‌اند. برای اینکه ببینید در کدام حالت هستید، از همان مفسری بپرسید که قصد اجرایش را دارید: ```bash python3 -c "import os, sys, sysconfig; print('venv:', sys.prefix != sys.base_prefix); print('marker:', os.path.isfile(os.path.join(sysconfig.get_path('stdlib'), 'EXTERNALLY-MANAGED')))" ``` pip فقط وقتی نصب را مسدود می‌کند که این فرمان `venv: False` و `marker: True` چاپ کند. درون یک محیط مجازی، نشانگر مفسر پایه همچنان دیده می‌شود، پس venv ما هم `marker: True` چاپ کرد، اما سطر اول `venv: True` بود و pip به‌طور عادی نصب کرد. ## کدام سیستم‌ها این نشانگر را دارند؟ Debian، Ubuntu، Raspberry Pi OS، Arch Linux و Homebrew آن را همراه دارند؛ Fedora و ایمیج‌های رسمی Docker ندارند. | سیستم | نشانگر | پیشنهاد پیام | |---|---|---| | ⁦Debian 12⁩ و بالاتر | دارد | `apt install python3-xyz`، venv، pipx | | ⁦Ubuntu 23.04⁩ و بالاتر | دارد | همان متن Debian | | Raspberry Pi OS Bookworm و بالاتر | دارد | همان متن Debian | | Arch Linux | دارد | `pacman -S python-xyz`، venv، pipx | | Python در Homebrew | دارد | `brew install xyz`، venv، pipx | | Fedora | ندارد | نصب‌های pip به `/usr/local` می‌روند | | ایمیج‌های رسمی `python` در Docker | ندارد | موضوعیت ندارد | Debian بسته ⁦Python 3.11⁩ خود را پیش از انتشار ⁦Debian 12⁩ علامت‌گذاری کرد و ⁦Ubuntu 23.04⁩ همان بسته را عرضه کرد، پس ⁦Ubuntu 24.04 LTS⁩ و سیستم‌های Ubuntu یا Debian که در WSL روی ویندوز اجرا می‌شوند همین پیام را نشان می‌دهند. Fedora راه دیگری می‌رود: هیچ نشانگری همراه ندارد و `sudo pip install` را به `/usr/local` می‌فرستد. ## راه‌حل اول: برای پروژه خود یک محیط مجازی بسازید محیط مجازی (virtual environment، به اختصار venv) پوشه‌ای است با `python` و پوشه بسته‌های مخصوص خودش که به مفسر سیستم پیوند دارد اما از بسته‌های آن جداست. pip درون آن بررسی ⁦PEP 668⁩ را انجام نمی‌دهد و هیچ چیزی که آنجا نصب کنید نمی‌تواند به سیستم دست بزند. ```bash cd ~/my-project python3 -m venv .venv source .venv/bin/activate python -m pip install requests ``` در آزمون ما، فرمان آخر با این سطر تمام شد: ```text Successfully installed certifi-2026.7.22 charset_normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0 ``` فعال‌سازی (activate) فقط پوشه `bin` محیط را در ابتدای `PATH` شما قرار می‌دهد. [مستندات venv در Python](https://docs.python.org/3/library/venv.html) فرمان هر پوسته (shell) را فهرست کرده است و در ویندوز این فرمان `.venv\Scripts\activate` است. می‌توانید فعال‌سازی را کنار بگذارید و مفسر محیط را مستقیم فراخوانی کنید؛ این شکل در اسکریپت‌ها، وظایف cron و سرویس‌های systemd امن‌تر است: ```bash .venv/bin/python -m pip install requests .venv/bin/python app.py ``` `.venv` را چیزی دورریختنی بدانید. آن را بیرون از Git نگه دارید (از ⁦Python 3.13⁩ به بعد، `venv` یک فایل `.gitignore` درون پوشه می‌نویسد)، بسته‌هایتان را با `python -m pip freeze > requirements.txt` ثبت کنید و در جای دیگر با `python -m pip install -r requirements.txt` دوباره بسازید. venv پس از جابه‌جا شدن یا کپی شدن به ماشینی دیگر سالم نمی‌ماند؛ آنجا آن را از نو بسازید. در VS Code، افزونه Python پوشه `.venv` را در فضای کاری پیدا می‌کند و آن را ترجیح می‌دهد. اگر مفسر دیگری را برگزید، Command Palette (پالت فرمان) را با ⁦Ctrl+Shift+P⁩ (در مک ⁦Cmd+Shift+P⁩) باز کنید، فرمان **⁦Python: Select Interpreter⁩** (انتخاب مفسر) را اجرا کنید و مفسر درون `.venv` را انتخاب کنید؛ از آن پس ترمینال‌های تازه با محیط فعال باز می‌شوند. ### خطای ⁦"ensurepip is not available"⁩ در Debian و Ubuntu Debian پشتیبانی `venv` را در بسته‌ای جداگانه عرضه می‌کند، پس روی یک سرور حداقلی (minimal) ممکن است خود فرمان `python3 -m venv .venv` شکست بخورد. ماژول `venv` وصله‌شده Debian این پیام را با شماره نسخه Python شما چاپ می‌کند: ```text The virtual environment was not created successfully because ensurepip is not available. On Debian/Ubuntu systems, you need to install the python3-venv package using the following command. apt install python3.13-venv ``` بسته را نصب کنید (`python3-venv` بسته مخصوص نسخه را هم با خود می‌آورد)، پوشه نیمه‌کاره را پاک کنید و فرمان را دوباره اجرا کنید: ```bash sudo apt install python3-venv rm -rf .venv python3 -m venv .venv ``` ## راه‌حل دوم: ابزارهای خط فرمان را با pipx نصب کنید اگر یک برنامه می‌خواهید نه یک کتابخانه، مثلاً یک قالب‌بند کد (formatter)، یک linter یا یک کلاینت HTTP، از pipx استفاده کنید، همان ابزاری که خود پیام خطا پیشنهاد می‌کند. pipx برای هر برنامه یک محیط مجازی جداگانه می‌سازد و فرمان‌هایش را در `PATH` شما می‌گذارد، پس ابزارها هرگز وابستگی‌های یکدیگر را خراب نمی‌کنند. ```bash sudo apt install pipx # macOS: brew install pipx pipx ensurepath pipx install ruff ``` پس از `pipx ensurepath` یک ترمینال تازه باز کنید. در آزمون ما، `pipx install ruff` پیام `installed package ruff 0.17.0` را گزارش داد و فرمان `ruff` بی‌درنگ کار کرد؛ بعدها `pipx upgrade ruff` و `pipx uninstall ruff` آن را مدیریت می‌کنند. [راهنمای نصب pipx](https://pipx.pypa.io/stable/how-to/install-pipx.html) فرمان‌های سیستم‌های دیگر را آورده است. ## راه‌حل سوم: از بسته خود توزیع استفاده کنید برای کتابخانه‌ای که یک اسکریپت سیستمی به آن نیاز دارد، شاید توزیع از قبل بسته‌ای آماده کرده باشد. Debian، Ubuntu و Raspberry Pi OS کتابخانه‌های Python را با الگوی `python3-` نام‌گذاری می‌کنند؛ Arch از `python-` استفاده می‌کند: ```bash sudo apt install python3-requests # Debian, Ubuntu, Raspberry Pi OS sudo pacman -S python-requests # Arch Linux ``` این نسخه‌ها به‌روزرسانی‌های امنیتی توزیع را دریافت می‌کنند، اما اغلب از آخرین انتشار در PyPI قدیمی‌ترند. Homebrew برنامه‌ها را بسته‌بندی می‌کند و مستنداتش برای کتابخانه‌ها شما را به venv ارجاع می‌دهد. گاهی یک پروژه به هر دو نیاز دارد: یک کتابخانه سخت‌افزاری از `apt` روی Raspberry Pi و یک بسته تازه‌تر از PyPI. محیط را با `python3 -m venv --system-site-packages .venv` بسازید. venv در این حالت بسته‌های سیستم را می‌بیند و pip همچنان فقط درون venv نصب می‌کند. در آزمون ما، `requests` در `.venv` نصب شد، در حالی که یک کتابخانه سیستمی که از قبل نصب بود از پوشه سیستم بارگذاری شد. ## راه‌حل چهارم: uv برای محیط‌ها و ابزارها uv یک مدیر بسته و پروژه است که چندین فرمان pip، venv و pipx را با یک برنامه جایگزین می‌کند. uv هم به نشانگر احترام می‌گذارد: `uv pip install --system` روی Python علامت‌گذاری‌شده ما با `error: The interpreter at … is externally managed` و پس از آن همان متن Debian متوقف شد. روند کاری معمول آن از یک محیط مجازی استفاده می‌کند، پس این خطا پیش نمی‌آید: ```bash uv venv uv pip install requests uv tool install ruff ``` `uv venv` پوشه `.venv` را در پوشه جاری می‌سازد، `uv pip install` بدون فعال‌سازی در آن نصب می‌کند و `uv tool install` همتای `pipx install` است. هر سه در آزمون ما کار کردند. ## کانتینرها و پایپ‌لاین‌های CI ایمیج‌های رسمی `python` در Docker Hub نسخه Python خود را در `/usr/local` کامپایل می‌کنند و نشانگری ندارند، پس `pip install` در آن‌ها مثل قبل کار می‌کند. خطا وقتی ظاهر می‌شود که یک Dockerfile از ایمیج `debian` یا `ubuntu` شروع کند و Python را با `apt` نصب کند. راه‌حل همان راه‌حل لپ‌تاپ است: `python3-venv` را نصب کنید، محیط را با `RUN python3 -m venv /opt/venv` بسازید و `ENV PATH="/opt/venv/bin:$PATH"` را اضافه کنید. از آن پس هر `RUN pip install -r requirements.txt` بعدی و `python` کانتینر از venv استفاده می‌کنند، درست مثل حالت پس از فعال‌سازی. سیستم‌های CI اغلب برای هر مرحله یک پوسته تازه باز می‌کنند، پس فعال‌سازی مرحله قبل از بین رفته است. در هر مرحله مفسر محیط را با مسیرش فراخوانی کنید (`.venv/bin/python -m pip install …`، `.venv/bin/python -m pytest`). ## چرا ⁦--break-system-packages⁩ آخرین چاره است؟ چون به‌جای حل تعارض، محافظت را خاموش می‌کند، و این کار واقعاً جواب می‌دهد: در بازتولید ما، `pip install --break-system-packages requests` بسته را در Python علامت‌گذاری‌شده نصب کرد و متغیر محیطی `PIP_BREAK_SYSTEM_PACKAGES=1` و سطر `break-system-packages = true` در بخش `[global]` یک فایل پیکربندی pip هم همین کار را کردند. این پرچم نصب را امن نمی‌کند و فقط هشدار را برمی‌دارد؛ pip از این پس ممکن است کتابخانه‌ای را که ابزارهای خود سیستم وارد می‌کنند ارتقا دهد یا حذف کند. یک به‌روزرسانی بعدی سیستم هم ممکن است روی آنچه pip نصب کرده بازنویسی کند. حذف فایل `EXTERNALLY-MANAGED` همین اثر را برای همه کاربران و برنامه‌های آن ماشین دارد. اگر واقعاً به این استثنا نیاز دارید، آن را جایی به کار ببرید که آسیب محدود بماند، مانند کانتینری که دوباره می‌سازید یا یک ماشین مجازی، و هرگز در پروفایل پوسته یا پیکربندی سراسری pip، که آنجا بی‌صدا روی همه نصب‌های بعدی اعمال می‌شود. ## چگونه pip را پشت سرور پروکسی به کار ببریم؟ آدرس پروکسی را با `--proxy`، متغیر `HTTPS_PROXY` یا فایل پیکربندی pip به آن بدهید. شبکه‌های شرکت‌ها و دانشگاه‌ها اغلب ترافیک وب را فقط از طریق سرور پروکسی‌ای اجازه می‌دهند که نام کاربری و رمز عبور می‌خواهد، و pip نبودِ اطلاعات ورود را مشکل پروکسی گزارش نمی‌کند. بدون اطلاعات ورود، پروکسی آزمون محلی ما به هر تلاش با کد وضعیت 407 پاسخ داد و pip پنج تلاش دوباره (چهارتای آن در زیر حذف شده‌اند) و نتیجه‌ای گمراه‌کننده چاپ کرد: ```text WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'OSError('Tunnel connection failed: 407 Proxy Authentication Required')': /simple/requests/ ERROR: Could not find a version that satisfies the requirement requests (from versions: none) ERROR: No matching distribution found for requests ``` `from versions: none` یعنی pip هرگز به فهرست بسته‌ها (package index) نرسیده است، نه اینکه بسته وجود ندارد. [راهنمای کاربری pip](https://pip.pypa.io/en/stable/user_guide/#using-a-proxy-server) همه گزینه‌ها را فهرست کرده است؛ این سه بیشتر حالت‌ها را پوشش می‌دهند: ```bash # for one command python -m pip install --proxy http://user:pass@proxy.example.com:8080 requests # for every command in this shell export HTTPS_PROXY=http://user:pass@proxy.example.com:8080 # stored in the active virtual environment only python -m pip config --site set global.proxy http://user:pass@proxy.example.com:8080 ``` هر سه روش `requests` را از طریق پروکسی آزمون ما نصب کردند. با `--site`، pip تنظیم را در فایل پیکربندی خود venv نوشت (`pip.conf`، یا `pip.ini` در ویندوز)؛ بدون آن، `pip config set` در فایل سطح کاربر شما می‌نویسد که روی همه محیط‌ها اعمال می‌شود. اگر رمز عبور شامل `@`، `:` یا `/` است، این نویسه‌ها را با کدگذاری درصدی (percent-encoding) بنویسید؛ [رفع خطای ⁦HTTP 407 Proxy Authentication Required⁩](/fa/blog/http-407-proxy-authentication-required) این کدگذاری و دیگر خطاهای اطلاعات ورود را شرح می‌دهد. پشت پروکسی‌ای که ترافیک HTTPS را بازرسی می‌کند، خطای بعدی معمولاً `CERTIFICATE_VERIFY_FAILED` است. ⁦pip 24.2⁩ و نسخه‌های بعدی به گواهی‌های سیستم‌عامل هم اعتماد می‌کنند، پس گواهی ریشه شرکتی که بخش IT در مخزن گواهی سیستم نصب کرده اغلب مشکل را رفع می‌کند، و گزینه `--cert` یک فایل بسته گواهی (CA bundle) را به pip معرفی می‌کند. [خطای ⁦Unable to Get Local Issuer Certificate⁩ و راه رفع آن](/fa/blog/unable-to-get-local-issuer-certificate) توضیح می‌دهد چگونه علت‌ها را از هم تشخیص دهید. ## چگونه از venv نخستین درخواست را از طریق پروکسی بفرستیم؟ وقتی `requests` در venv نصب شد، درخواست از طریق پروکسی فقط یک دیکشنری لازم دارد. اسکریپت آدرس پروکسی را از یک متغیر محیطی می‌خواند، پس اطلاعات ورود بیرون از کد می‌ماند: ```python import os import sys import requests # The endpoint and credentials from your proxy dashboard PROXY = os.environ.get("PROXY_URL", "http://user:pass@pr.proxynet.io:8000") proxies = {"http": PROXY, "https": PROXY} print("Python:", sys.executable) try: r = requests.get("https://example.com/", proxies=proxies, timeout=15) print("Status:", r.status_code) except requests.exceptions.ProxyError as err: print("Proxy error:", err) ``` آن را با `.venv/bin/python first_request.py` اجرا کنید. از طریق پروکسی آزمون محلی ما، سطر `Python:` مفسر درون `.venv` را نشان داد و سطر دوم `Status: 200` بود. با رمز عبور نادرست، اسکریپت یک `Proxy error` چاپ کرد که با `Tunnel connection failed: 407 Proxy Authentication Required` تمام می‌شد. وقتی با `python3` سیستم اجرا شد، اسکریپت اصلاً به آنجا نرسید و خطای `ModuleNotFoundError: No module named 'requests'` داد، چون بسته‌ها در venv قرار دارند. نوع پروکسی تعیین می‌کند سایت‌های مقصد درخواست‌های شما را چگونه ببینند. [پروکسی مسکونی](https://proxynet.io/fa/residential-proxy) از طریق اتصال‌های خانگی در کشور و شهری که انتخاب می‌کنید خارج می‌شود، با آدرسی تازه برای هر درخواست یا یک نشست ثابت (sticky session) از 1 تا 60 دقیقه؛ از آن برای دیدن صفحه‌ها همان‌طور که بازدیدکنندگان محلی می‌بینند استفاده کنید، در چارچوب شرایط استفاده و محدودیت نرخ هر سایت. [پروکسی دیتاسنتر](https://proxynet.io/fa/datacenter-proxy) آدرس‌های ⁦IPv4⁩ اختصاصی با ترافیک بدون سهمیه در اختیارتان می‌گذارد که برای کارهای منظم، مانند بررسی سرویس‌ها و APIهای خودتان از چند کشور، مناسب است. برای ارسال داده به‌جای دریافت آن، [ارسال JSON با POST در Python Requests](/fa/blog/python-requests-post-json) پارامتر `json=`، هدرها و فرمان‌های cURL متناظر را پوشش می‌دهد. ## کجا با این خطا روبه‌رو می‌شوید - **سرورها و ایمیج‌های VPS تازه** روی ⁦Debian 12⁩ یا بالاتر یا ⁦Ubuntu 24.04⁩، جایی که اسکریپت‌های راه‌اندازی قدیمی هنوز `sudo pip install` را فراخوانی می‌کنند. - **پروژه‌های Raspberry Pi** که از آموزش‌های قدیمی‌تر برای کتابخانه‌های حسگر و GPIO پیروی می‌کنند. - **مک‌هایی** که `python3` در آن‌ها از Homebrew می‌آید. - **Dockerfileهایی** بر پایه ایمیج‌های `debian` یا `ubuntu` که Python را با `apt` نصب می‌کنند. - **WSL در ویندوز**، که Ubuntu یا Debian را اجرا می‌کند. - **کارهای CI** پس از اینکه ایمیج پایه به نسخه تازه‌تری منتقل شود. ## اشتباه‌های رایج - **اجرای `sudo pip install` درون یک venv فعال.** در Debian، `sudo` متغیر `PATH` را با فهرستی ثابت (`secure_path`) جایگزین می‌کند، pip سیستم را پیدا می‌کند و خطا برمی‌گردد. venv در پوشه خانگی شما به `sudo` نیازی ندارد. - **نصب در venv اما اجرا با `python3`.** مفسر سیستم بسته‌های venv را نمی‌بیند و با `ModuleNotFoundError` شکست می‌خورد. - **افزودن `.venv` به Git یا کپی آن به ماشینی دیگر.** آن را از روی `requirements.txt` دوباره بسازید. - **تنظیم `break-system-packages` در پیکربندی سراسری pip.** این کار محافظت را برای همه نصب‌های بعدی خاموش می‌کند. ## راهنمای انتخاب | هدف شما | ابزار مناسب | |---|---| | کتابخانه‌های یک پروژه | `python3 -m venv .venv` | | یک ابزار خط فرمان | `pipx install ` | | یک کتابخانه برای اسکریپت سیستمی | `apt install python3-` | | بسته‌های سیستم به‌همراه بسته‌های PyPI | `venv --system-site-packages` | | یک ابزار برای محیط‌ها و ابزارها | `uv venv`، `uv tool install` | | ایمیج Docker بر پایه Debian یا Ubuntu | venv در `/opt/venv`، در ابتدای `PATH` | | pip پشت پروکسی شرکتی | `--proxy` یا `HTTPS_PROXY` | | کانتینری که دور می‌اندازید | `--break-system-packages` | ## پرسش‌های متداول ### چرا پس از ارتقای Ubuntu یا Debian دستور pip install دیگر کار نمی‌کند؟ نسخه تازه شما نشانگر `EXTERNALLY-MANAGED` را همراه دارد و ⁦pip 23.0⁩ و نسخه‌های بعدی به آن پایبندند. ⁦Debian 12⁩ و ⁦Ubuntu 23.04⁩ نخستین نسخه‌هایی بودند که این فایل را داشتند، پس ارتقا از ⁦Debian 11⁩ یا ⁦Ubuntu 22.04⁩ رایج‌ترین عامل است. ### آیا استفاده از ⁦--break-system-packages⁩ امن است؟ نه روی سیستمی که می‌خواهید نگهش دارید. این گزینه به pip اجازه می‌دهد کتابخانه‌هایی را که ابزارهای Python خود سیستم‌عامل وارد می‌کنند جایگزین یا حذف کند. فقط در کانتینر یا ماشین مجازی‌ای از آن استفاده کنید که می‌توانید دوباره بسازید. ### آیا ⁦pip install --user⁩ از این خطا جلوگیری می‌کند؟ خیر. این بررسی به مفسر نگاه می‌کند، نه به پوشه کاربری که فایل‌ها به آن می‌روند، پس نصب‌های `--user` هم مسدود می‌شوند؛ آزمون ما هم این را تأیید کرد. ### آیا می‌توانم فایل EXTERNALLY-MANAGED را حذف کنم؟ می‌توانید، اما این کار محافظت را برای همه کاربران و برنامه‌های آن ماشین خاموش می‌کند، درست مانند یک `--break-system-packages` سراسری، و به‌روزرسانی بعدی بسته Python ممکن است فایل را برگرداند. یک venv مشکل را بدون هیچ‌یک از این دو عارضه حل می‌کند. ### آیا باید هر بار محیط مجازی را فعال کنم؟ خیر. فعال‌سازی فقط `PATH` را برای پوسته جاری تغییر می‌دهد. فراخوانی `.venv/bin/python` (در ویندوز `.venv\Scripts\python.exe`) مستقیماً از محیط استفاده می‌کند و برای اسکریپت‌ها، سرویس‌ها و CI شکل قابل‌اعتماد همین است. ### چرا pip درون محیط مجازی من هنوز این خطا را نشان می‌دهد؟ در این صورت، pip اجراشده متعلق به venv نیست: علت `sudo` است، یا ترمینالی تازه بدون فعال‌سازی، یا ترمینال ویرایشگری که از مفسر سیستم استفاده می‌کند. `python -m pip --version` را اجرا کنید؛ مسیری که چاپ می‌کند باید به درون `.venv` اشاره کند. ## خلاصه `error: externally-managed-environment` راهی است که سیستم‌عامل به pip می‌گوید Python سیستم چیزی نیست که pip تغییرش دهد. به هر پروژه یک محیط مجازی بدهید، به هر ابزار خط فرمان با pipx محیط خودش را بدهید و Python سیستم را به `apt`، `pacman` یا Homebrew بسپارید. `--break-system-packages` را برای ماشین‌هایی نگه دارید که می‌توانید دور بیندازید. وقتی اسکریپت‌هایتان باید از موقعیت‌های دیگر به سایت‌ها برسند، [خدمات پروکسی ما](/fa/proxy) را ببینید.