خطای ⁦externally-managed-environment⁩ در pip و راه رفع آن

یک سرور تازه ⁦Ubuntu 24.04⁩، یک Raspberry Pi یا یک مک با Homebrew راه‌اندازی می‌کنید، مثل سال‌های گذشته pip install requests را تایپ می‌کنید و pip با error: externally-managed-environment متوقف می‌شود. همان فرمان روی دستگاه قدیمی‌تان هنوز کار می‌کند و پیام از شما می‌خواهد به‌جای آن از apt، یک محیط مجازی یا pipx استفاده کنید.

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

پیام ⁦error: externally-managed-environment⁩ یعنی چه؟#

یعنی pip نشانگری پیدا کرده که می‌گوید ابزار دیگری صاحب این نصب Python است. ⁦PEP 668⁩ این نشانگر را تعریف می‌کند: فایلی به نام 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 می‌بینند یکی است:

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-<language> داشته باشد، از آن کلید، و آن را چاپ می‌کند.
4. هم pip install و هم pip uninstall را مسدود می‌کند. --user کمکی نمی‌کند: در آزمون ما pip install --user requests با همان خطا متوقف شد. اجرای pip با sudo هم چیزی را تغییر نمی‌دهد.
5. گزینه --break-system-packages این بررسی را کنار می‌گذارد، و شکل‌های متغیر محیطی و فایل پیکربندی آن هم همین کار را می‌کنند که در ادامه آمده‌اند.

برای اینکه ببینید در کدام حالت هستید، از همان مفسری بپرسید که قصد اجرایش را دارید:

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 بسته ⁦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⁩ را انجام نمی‌دهد و هیچ چیزی که آنجا نصب کنید نمی‌تواند به سیستم دست بزند.

cd ~/my-project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests

در آزمون ما، فرمان آخر با این سطر تمام شد:

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 فرمان هر پوسته (shell) را فهرست کرده است و در ویندوز این فرمان .venv\Scripts\activate است. می‌توانید فعال‌سازی را کنار بگذارید و مفسر محیط را مستقیم فراخوانی کنید؛ این شکل در اسکریپت‌ها، وظایف cron و سرویس‌های systemd امن‌تر است:

.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 شما چاپ می‌کند:

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

sudo apt install python3-venv
rm -rf .venv
python3 -m venv .venv

راه‌حل دوم: ابزارهای خط فرمان را با pipx نصب کنید#

اگر یک برنامه می‌خواهید نه یک کتابخانه، مثلاً یک قالب‌بند کد (formatter)، یک linter یا یک کلاینت HTTP، از pipx استفاده کنید، همان ابزاری که خود پیام خطا پیشنهاد می‌کند. pipx برای هر برنامه یک محیط مجازی جداگانه می‌سازد و فرمان‌هایش را در PATH شما می‌گذارد، پس ابزارها هرگز وابستگی‌های یکدیگر را خراب نمی‌کنند.

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 فرمان‌های سیستم‌های دیگر را آورده است.

راه‌حل سوم: از بسته خود توزیع استفاده کنید#

برای کتابخانه‌ای که یک اسکریپت سیستمی به آن نیاز دارد، شاید توزیع از قبل بسته‌ای آماده کرده باشد. Debian، Ubuntu و Raspberry Pi OS کتابخانه‌های Python را با الگوی python3-<name> نام‌گذاری می‌کنند؛ Arch از python-<name> استفاده می‌کند:

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

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 پنج تلاش دوباره (چهارتای آن در زیر حذف شده‌اند) و نتیجه‌ای گمراه‌کننده چاپ کرد:

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 همه گزینه‌ها را فهرست کرده است؛ این سه بیشتر حالت‌ها را پوشش می‌دهند:

# 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⁩ این کدگذاری و دیگر خطاهای اطلاعات ورود را شرح می‌دهد.

پشت پروکسی‌ای که ترافیک HTTPS را بازرسی می‌کند، خطای بعدی معمولاً CERTIFICATE_VERIFY_FAILED است. ⁦pip 24.2⁩ و نسخه‌های بعدی به گواهی‌های سیستم‌عامل هم اعتماد می‌کنند، پس گواهی ریشه شرکتی که بخش IT در مخزن گواهی سیستم نصب کرده اغلب مشکل را رفع می‌کند، و گزینه --cert یک فایل بسته گواهی (CA bundle) را به pip معرفی می‌کند. خطای ⁦Unable to Get Local Issuer Certificate⁩ و راه رفع آن توضیح می‌دهد چگونه علت‌ها را از هم تشخیص دهید.

چگونه از venv نخستین درخواست را از طریق پروکسی بفرستیم؟#

وقتی requests در venv نصب شد، درخواست از طریق پروکسی فقط یک دیکشنری لازم دارد. اسکریپت آدرس پروکسی را از یک متغیر محیطی می‌خواند، پس اطلاعات ورود بیرون از کد می‌ماند:

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 قرار دارند.

نوع پروکسی تعیین می‌کند سایت‌های مقصد درخواست‌های شما را چگونه ببینند. پروکسی مسکونی از طریق اتصال‌های خانگی در کشور و شهری که انتخاب می‌کنید خارج می‌شود، با آدرسی تازه برای هر درخواست یا یک نشست ثابت (sticky session) از 1 تا 60 دقیقه؛ از آن برای دیدن صفحه‌ها همان‌طور که بازدیدکنندگان محلی می‌بینند استفاده کنید، در چارچوب شرایط استفاده و محدودیت نرخ هر سایت.

پروکسی دیتاسنتر آدرس‌های ⁦IPv4⁩ اختصاصی با ترافیک بدون سهمیه در اختیارتان می‌گذارد که برای کارهای منظم، مانند بررسی سرویس‌ها و APIهای خودتان از چند کشور، مناسب است. برای ارسال داده به‌جای دریافت آن، ارسال JSON با POST در Python Requests پارامتر 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. این کار محافظت را برای همه نصب‌های بعدی خاموش می‌کند.

راهنمای انتخاب#

پرسش‌های متداول#

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