تفاوت venv، pipx و uv در مدیریت پایتون روی سرور
خطای externally-managed-environment در Ubuntu 24.04 مانع نصب با pip میشود. با انتخاب صحیح بین venv، pipx یا uv برای پروژهها و ابزارهای خود، از تداخل با بستههای سیستم جلوگیری کنید.
چرا دستور pip install روی یک سرور تازه Ubuntu با خطا مواجه میشود
انتخاب بین Python venv، pipx و uv روی یک سرور به یک پرسش اساسی برمیگردد: چه چیزی نصب میکنید؟ وابستگیهای یک برنامه باید در یک محیط مجازی (virtual environment) درون دایرکتوری همان برنامه قرار بگیرند. ابزارهای خط فرمانی که میخواهید با نامشان آنها را اجرا کنید، باید با pipx نصب شوند. ابزار uv هر دو کار را انجام میدهد و یک فایل lockfile نیز اضافه میکند که بهمحض نیاز به ساخت محیط مشابه روی ماشین دوم، اهمیت پیدا میکند. هیچکدام از این ابزارها در Python سیستمی نصب نمیکنند، زیرا نسخههای فعلی Ubuntu بهطور کامل مانع این کار میشوند.
اگر sudo pip install requests را روی Ubuntu 24.04 اجرا کنید، pip پیش از دانلود حتی یک فایل، متوقف میشود.
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.
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.
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this behaviour by passing --break-system-packages.این رفتار ناشی از اجرای PEP 668 (پیشنهاد بهبود پایتون 668، "محیطهای مدیریتشده خارجی") است. توزیعهای Debian و Ubuntu یک فایل نشانگر در کنار مفسر در مسیر /usr/lib/python3.12/EXTERNALLY-MANAGED قرار میدهند و pip از نوشتن در هر مفسری که این فایل را داشته باشد، خودداری میکند.
این قانون به دلیل ترتیب sys.path وجود دارد. apt کتابخانهها را در /usr/lib/python3/dist-packages نصب میکند. اگر pip را با دسترسی root روی مفسر سیستم اجرا کنید، فایلها را در /usr/local/lib/python3.12/dist-packages مینویسد و بستهبندی Debian این دایرکتوری را در اولویت بالاتری در مسیر جستجو قرار میدهد. خودتان میتوانید با اجرای python3 -c 'import sys; print(sys.path)' این ترتیب را چاپ و مشاهده کنید. بنابراین، نسخهای که pip نوشته است، جایگزین نسخهای میشود که apt نصب کرده؛ این اتفاق برای تمام برنامههایی که تحت /usr/bin/python3 اجرا میشوند، از جمله ابزارهای خود توزیع، رخ میدهد. برای مثال، cloud-init کتابخانههای requests، jinja2 و PyYAML را از همان مفسر فراخوانی میکند. اگر یکی از آنها را با pip ارتقا دهید و به یک نسخه ناسازگار برسید، برنامهای که هرگز به آن دست نزدهاید در بوت بعدی با یک traceback که نام بستهای ناشناخته را ذکر میکند، از کار میافتد. از آنجا که apt همچنان نسخه خود را به عنوان نسخه نصبشده ثبت کرده است، هیچ هشداری دریافت نمیکنید. راه تعمیر، حذف نسخه pip با sudo pip uninstall --break-system-packages requests است، زیرا sudo apt reinstall python3-requests بهتنهایی فقط نسخه apt را که قبلاً تحتالشعاع قرار گرفته بود، بازنویسی میکند.
قانون حاصل کوتاه است: Python سیستمی متعلق به توزیع است. در آن چیزی نصب نکنید، کتابخانههای آن را با pip ارتقا ندهید و فایل EXTERNALLY-MANAGED را برای حذف پیام خطا پاک نکنید. تنها وظیفهای که باید به /usr/bin/python3 محول کنید، ساخت محیطهای مجازی است.
مقایسه venv در برابر pipx و uv: قاعده تصمیمگیری
انتخاب ابزار را بر اساس ماهیت چیزی که نصب میکنید انجام دهید، نه بر اساس ابزاری که اخیراً درباره آن مطالعه کردهاید.
- برنامهای که آن را مستقر کرده و به عنوان یک سرویس اجرا میکنید، مانند پروژههای Django یا Flask: از یک محیط مجازی (venv) در داخل دایرکتوری همان برنامه استفاده کنید.
- ابزار خط فرمانی که میخواهید روی
PATHخود داشته باشید، مانندansibleیاhttpie: از pipx استفاده کنید؛ این ابزار برای هر برنامه یک محیط اختصاصی ایجاد کرده و یک لینک درPATHقرار میدهد. - پروژهای که به lockfile، سرعت نصب بالاتر یا نسخهای از Python نیاز دارد که در توزیع سیستمعامل موجود نیست: از uv استفاده کنید که یک venv معمولی به همراه یک فایل
uv.lockتولید میکند. - کتابخانهای که یک ابزار توزیعشده به آن نیاز دارد و نه کد شما: از
sudo apt install python3-<name>استفاده کنید؛ این تنها روش پشتیبانیشده برای افزودن هر چیزی به مفسر سیستم است.
ابزارهای pipx و uv tool install وظیفه یکسانی دارند، بنابراین سیستمی که از قبل uv دارد، نیازی به pipx نخواهد داشت. انتخاب فریمورک وب هیچ تغییری در این قاعده ایجاد نمیکند: Django و Flask روی یک VPS در محتوای requirements.txt تفاوت دارند، نه در نحوه ساخت محیط پیرامون آن. تمام موارد زیر از Ubuntu 24.04 و Python 3.12 استفاده میکنند، بنابراین اگر نسخه شما متفاوت است، شماره نسخه را در مسیرها اصلاح کنید.
ساخت venv برای هر برنامه
اوبونتو ماژول venv را از بسته اصلی Python جدا کرده است، بنابراین در یک image حداقلی، اولین تلاش با پیامی که دقیقاً نام بسته مفقود را اعلام میکند، با شکست مواجه میشود.
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.12-venvآن را نصب کنید و سپس محیط را با کاربری که مالک کد خواهد بود، ایجاد نمایید.
sudo apt update
sudo apt install -y python3-venv
sudo install -d -o deploy -g deploy -m 755 /srv/myapp
sudo -u deploy python3 -m venv /srv/myapp/.venv
sudo -u deploy /srv/myapp/.venv/bin/pip install -r /srv/myapp/requirements.txtبه آنچه وجود ندارد دقت کنید: نه source و نه activate. دستور /srv/myapp/.venv/bin/pip به دلیل موقعیت باینری در آن محیط نصب میشود، نه به دلیل چیزی که در shell صادر کردهاید. پیش از ادامه، این موضوع را تأیید کنید.
/srv/myapp/.venv/bin/python -c 'import sys; print(sys.prefix)'این دستور /srv/myapp/.venv را چاپ میکند. اگر /usr را چاپ کرد، شما در حال اجرای مفسر سیستم هستید و بستههای شما به جایی رفتهاند که قصد آن را نداشتید.
دو ویژگی یک venv تعیین میکند که پس از آن چه کاری میتوانید انجام دهید. یک venv قابل انتقال (relocatable) نیست، زیرا هر اسکریپت entry-point در bin/ دارای یک خط shebang مطلق است: head -1 /srv/myapp/.venv/bin/pip فایل #!/srv/myapp/.venv/bin/python را میخواند. اگر دایرکتوری والد را تغییر نام دهید، آن اسکریپتها با خطای bad interpreter: No such file or directory مواجه میشوند. یک venv همچنین مفسری که آن را ایجاد کرده است را ثابت نگه میدارد که به عنوان خط home در /srv/myapp/.venv/pyvenv.cfg ثبت شده است و bin/python3 یک symlink به /usr/bin/python3 است. اگر نسخه را ارتقا دهید به طوری که آن مسیر اکنون به یک Python جدیدتر اشاره کند، مفسر جدید به دنبال بستهها در دایرکتوری lib/python3.13 میگردد که venv آن را ندارد، بنابراین سرویس در هنگام شروع با خطای ModuleNotFoundError متوقف میشود. هر دو مورد راه حل یکسانی دارند: venv را حذف کنید و یک نمونه جدید از requirements.txt بسازید. بازسازی تنها چند ثانیه زمان میبرد. هرگز یک venv را بین ماشینها کپی نکنید.
محل قرارگیری venv و مالکیت آن
آن را در کنار کد در مسیر /srv/myapp/.venv قرار دهید و برای هر برنامه یک venv مجزا در نظر بگیرید. در این صورت، استقرار برنامه شامل یک دایرکتوری واحد خواهد بود، unit مربوط به systemd مسیری ثابت خواهد داشت و دو برنامه هرگز با ارتقای وابستگیهای مشترک، یکدیگر را دچار اختلال نمیکنند. venv را در هیچ مسیری که وبسرور شما مستقیماً فایلهای آن را منتشر میکند قرار ندهید، زیرا این محیط حاوی وابستگیها و اغلب تنظیمات شماست.
مالکیت فایلها نیازمند کمی دقت است. اجازه دهید یک کاربر deploy مالک کد و محیط باشد و به حساب کاربری سرویس، فقط دسترسی خواندن و اجرا بدهید.
sudo adduser --system --group --no-create-home myapp
sudo chown -R deploy:myapp /srv/myapp
sudo chmod -R o-rwx /srv/myappسرویس اکنون میتواند وابستگیهای خود را فراخوانی کند اما قادر به بازنویسی آنها نیست؛ این یعنی یک باگ اجرای کد در برنامه وب نمیتواند بیسروصدا یک کتابخانه را روی دیسک جایگزین کند و پس از راهاندازی مجدد نیز باقی بماند. همین استدلال برای سایر بخشهای سیستم در اجرای سرویسها با کاربر دارای حداقل دسترسی پوشش داده شده است.
استفاده از pipx برای ابزارهای خط فرمان
ابزار pipx برای نصب برنامهها کاربرد دارد، نه کتابخانهها. هر ابزار محیط اختصاصی خود را در ~/.local/share/pipx/venvs/<name> دریافت میکند و فایلهای اجرایی آن در ~/.local/bin لینک میشوند؛ بنابراین دو ابزاری که به نسخههای متفاوتی از یک کتابخانه نیاز دارند، هرگز با هم تداخل پیدا نمیکنند.
sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install httpieدستور pipx ensurepath با ویرایش فایل راهانداز shell، مسیر ~/.local/bin را به PATH اضافه میکند. این دستور نمیتواند shell فعلی شما را تغییر دهد، بنابراین خطای http: command not found بلافاصله پس از نصب معمولاً به این معنی است که شما هنوز از سیستم خارج و دوباره وارد نشدهاید. فایل ~/.profile پیشفرض در Ubuntu، مسیر ~/.local/bin را تنها زمانی به PATH اضافه میکند که آن دایرکتوری در لحظه ورود به سیستم وجود داشته باشد؛ به همین دلیل است که این مشکل فقط یکبار در حسابهای کاربری جدید رخ میدهد.
اگر pipx را به سمت یک کتابخانه هدایت کنید، با پیامی که با عبارت زیر شروع میشود، از انجام آن خودداری میکند:
No apps associated with package requests.این پیام به شما میگوید که از ابزار اشتباهی استفاده میکنید. کتابخانهها باید در venv مربوط به یک برنامه قرار بگیرند.
نکته مهم در سرور، محل نصب است. اجرای ساده pipx install همه چیز را در دایرکتوری home یک کاربر قرار میدهد. یک unit در systemd که با کاربر myapp اجرا میشود، یک cron job که با root اجرا میشود و حتی sudo نمیتوانند آن را ببینند، زیرا secure_path در /etc/sudoers، مقدار PATH را با یک لیست ثابت جایگزین میکند. برای ابزاری که کل سیستم باید به آن دسترسی داشته باشد، آن را بهصورت سراسری (globally) نصب کنید.
sudo pipx install --global ansible
sudo pipx ensurepath --globalفلگ --global محیطها را در /opt/pipx قرار داده و فایلهای اجرایی را در /usr/local/bin لینک میکند که در PATH پیشفرض و داخل secure_path قرار دارد. ابتدا نسخه خود را با pipx --version بررسی کنید، زیرا Ubuntu 24.04 شامل نسخه 1.4.3 از pipx است که قدیمیتر از --global میباشد و نسخههای قدیمیتر pipx با unrecognized arguments: --global پاسخ میدهند. در آن نسخه، دو دایرکتوری مستند شده را خودتان تنظیم کنید:
sudo env PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ansible
command -v ansibleدستور command -v ansible باید /usr/local/bin/ansible را چاپ کند. اگر خروجی آن مسیری در /home باشد، ابزار در حساب کاربری یک کاربر خاص نصب شده است و هیچ سرویسی آن را پیدا نخواهد کرد.
uv زمانی که به یک lockfile نیاز دارید
ابزار uv یک فایل اجرایی واحد از Astral است که وظایف pip، venv و pip-tools را پوشش میدهد و همچنین میتواند مفسرهای پایتون را دانلود کند. سرعت این ابزار بهقدری بالاست که تفاوت آن حتی در یک VPS کوچک نیز محسوس است و یک lockfile واقعی ایجاد میکند.
نصبکننده رسمی، uv و uvx را در ~/.local/bin قرار میدهد:
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --versionپایپ کردن یک اسکریپت به shell در سرور، نیازمند لحظهای دقت است. نسخه موجود در URL را ثابت (Pin) کنید و پیش از اجرا، محتوای فایل را بخوانید:
curl -LsSf https://astral.sh/uv/0.12.3/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.shاگر pipx از قبل نصب باشد، pipx install uv نیز کار میکند. ابزار uv یک فایل اجرایی مستقل است و وابستگی پایتونی ندارد؛ بنابراین کپی کردن آن در /usr/local/bin روشی معتبر برای در دسترس قرار دادن آن برای تمام کاربران سیستم است.
برای پروژهای که دارای pyproject.toml است، گردش کار شامل چهار دستور است که تنها دستور آخر روی سرور اجرا میشود.
uv init myapp
uv add flask gunicorn
uv lock
uv sync --frozen --no-devدستور uv lock فایل uv.lock را مینویسد که یک lockfile چندسکویی (cross-platform) حاوی نسخههای دقیق و حلشده است و باید آن را همراه با کد خود commit کنید. دستور uv sync محیط .venv را در ریشه پروژه مطابق با آن میسازد. روی سرور، پرچم --frozen اهمیت دارد: مستندات آن را به عنوان استفاده از نسخههای موجود در lockfile به عنوان منبع حقیقت تعریف میکنند، بهجای اینکه بررسی کند آیا lockfile بهروز است یا خیر؛ این همان رفتاری است که برای استقرار (deployment) نیاز دارید. پرچم --no-dev گروه وابستگیهای توسعه (development) را نادیده میگیرد.
یک پروژه requirements.txt موجود نیازی به تبدیل ندارد، زیرا uv زبان pip را میفهمد:
uv venv /srv/myapp/.venv
uv pip install --python /srv/myapp/.venv/bin/python -r /srv/myapp/requirements.txtخروجی، یک محیط مجازی (virtual environment) معمولی است با یک تفاوت: uv ابزار pip را درون آن نصب نمیکند، بنابراین .venv/bin/pip و .venv/bin/python -m pip کار نمیکنند مگر اینکه محیط را با uv venv --seed ایجاد کنید. در عوض، از uv pip برای نصب استفاده کنید. هیچکدام از مراحل بعدی این راهنما از pip درون محیط استفاده نمیکنند، بنابراین تغییری ایجاد نخواهد شد.
یک تنظیم پیشفرض در uv وجود دارد که پیش از استفاده روی سرور باید از آن آگاه باشید. تنظیم python-preference بهصورت پیشفرض روی managed است که طبق مستندات، مفسرهایی را انتخاب میکند که «توسط uv دانلود و نصب شدهاند» و مفسرهای موجود در سیستم را نادیده میگیرد. بنابراین، uv venv --python 3.13 روی سیستمی که فقط پایتون 3.12 دارد، بهجای خطا دادن، بیسروصدا نسخه 3.13 را در ~/.local/share/uv/python دانلود میکند. این رفتار روی لپتاپ راحت است اما روی سرور غافلگیرکننده است، زیرا سرویس شما اکنون به مفسری وابسته است که در یک دایرکتوری خانگی (home directory) قرار دارد و apt upgrade هرگز آن را وصله (patch) نخواهد کرد. اگر مفسر توزیع سیستمعامل را میخواهید، python-preference را در uv.toml روی only-system تنظیم کنید. اگر میخواهید محیط مجازی در جایی غیر از ریشه پروژه باشد، UV_PROJECT_ENVIRONMENT دایرکتوری مورد نظر برای محیط مجازی پروژه را مشخص میکند.
اشاره به مفسر venv در systemd، نه به activate
اینجاست که اکثر استقرارهای Python با شکست مواجه میشوند و علت آن، درک نادرست از عملکرد activate است.
bin/activate یک اسکریپت shell است. این اسکریپت دایرکتوری bin مربوط به venv را به ابتدای PATH اضافه میکند، VIRTUAL_ENV را تنظیم میکند، مقادیر قبلی را ذخیره میکند تا deactivate بتواند آنها را بازیابی کند و prompt شما را تغییر میدهد. این اسکریپت حاوی هیچ چیزی نیست که خود مفسر آن را بخواند. فعالسازی (activation) صرفاً یک راحتی برای انسانی است که python را در یک prompt تایپ میکند.
آنچه در واقع محیط را انتخاب میکند، این است که کدام فایل مفسر را اجرا میکنید. وقتی /srv/myapp/.venv/bin/python شروع به کار میکند، ماژول site در Python به دنبال یک فایل pyvenv.cfg در دایرکتوری حاوی فایل اجرایی و یک سطح بالاتر از آن میگردد. پیدا کردن /srv/myapp/.venv/pyvenv.cfg باعث میشود sys.prefix روی venv تنظیم شود، که این کار site-packages مربوط به آن venv را در sys.path قرار میدهد. این تمام مکانیزم است. این کار به هیچ متغیر محیطی و هیچ shell نیاز ندارد.
بنابراین این unit هرگز شروع نمیشود:
[Service]
ExecStart=source /srv/myapp/.venv/bin/activate && gunicorn app:appmyapp.service: Failed to locate executable source: No such file or directory
myapp.service: Failed at step EXEC spawning source: No such file or directory
myapp.service: Main process exited, code=exited, status=203/EXECExecStart یک خط فرمان shell نیست. systemd یک برنامه را مستقیماً اجرا میکند، بنابراین هیچ builtin مربوط به source وجود ندارد، && به عنوان یک آرگومان متنی (literal) ارسال میشود و هیچکدام از بسطهای (expansions) shell فراتر از مواردی که خود systemd مستند کرده است، اتفاق نمیافتد.
و این unit شروع میشود، اما سپس از کار میافتد:
[Service]
ExecStart=/usr/bin/python3 /srv/myapp/app.pyModuleNotFoundError: No module named 'flask'/usr/bin/python3 مفسر سیستم است و sys.path آن هرگز حاوی venv شما نبوده است. همان دستور در session مربوط به SSH شما کار میکند فقط به این دلیل که شما venv را در آنجا فعال کرده بودید، بنابراین shell توانست python3 را از طریق PATH به .venv/bin/python3 تبدیل کند.
قرار دادن دستور داخل /bin/bash -c 'source ... && gunicorn ...' کار میکند. اما این کار یک shell را بین systemd و پردازش شما بدون هیچ دستاوردی قرار میدهد، در حالی که یک مسیر مطلق (absolute path) مشکل را حل میکند:
[Unit]
Description=myapp web service
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp
Environment=PYTHONUNBUFFERED=1
Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/srv/myapp/.venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 app:app
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now myapp
systemctl status myapp
journalctl -u myapp -n 50 --no-pagersystemctl status myapp باید active (running) را با یک Main PID که همان پردازش gunicorn شماست، گزارش دهد. در غیر این صورت، journal را بخوانید.
خط Environment=PATH= برای ExecStart وجود ندارد، چرا که آن قبلاً مسیر کامل را حمل میکند. این خط برای پردازشهایی است که برنامه شما شروع میکند. یک سرویس، یک PATH پیشفرض کوتاه از systemd به ارث میبرد، بنابراین کد Python که subprocess.run(["ffmpeg", ...]) را فراخوانی میکند، یا یک دستور مدیریتی که به یک اسکریپت کنسول از venv ارجاع میدهد، آنچه نیاز دارد را پیدا نخواهد کرد. قرار دادن دایرکتوری bin مربوط به venv در ابتدای مسیر، تنها بخشی از activate است که یک سرویس واقعاً از آن استفاده میکند. بررسی کنید که unit واقعاً با systemctl show -p Environment myapp چه چیزی دریافت کرده است.
همین قانون شامل کارهای زمانبندیشده نیز میشود. در Ubuntu، برنامه cron متغیر PATH را از shell شما یا از daemon به job منتقل نمیکند: مگر اینکه crontab خودش PATH را تنظیم کند، هر job مقدار پیشفرض کامپایلشده /usr/bin:/bin را دریافت میکند و /etc/environment آن را بازنویسی نمیکند. این مقدار هرگز حاوی venv شما نیست، بنابراین یک خط crontab که python3 /srv/myapp/cleanup.py را میخواند، مفسر سیستم را اجرا کرده و ساعت 3 صبح با ModuleNotFoundError شکست میخورد. cron خطا را به مالک crontab یا به آدرس MAILTO (اگر آن را تنظیم کرده باشید) ایمیل میکند، که در اکثر سرورها به معنای یک صندوق پستی محلی است که هیچکس آن را نمیخواند. بدون نصب برنامه ایمیل، cron خروجی را دور میریزد و فقط No MTA installed, discarding output را در لاگ سیستم مینویسد. مسیر مطلق venv را در آنجا نیز بنویسید. برای دریافت آن خروجی در journal و داشتن سوابق آخرین اجرا، یک جفت سرویس و تایمر systemd همان خط ExecStart را میپذیرد.
آیا Docker این تصمیم را جایگزین میکند؟
هر کانتینر فایلسیستم اختصاصی خود را دارد، بنابراین صورت مسئله تغییر میکند اما از بین نمیرود. در یک ایمیج رسمی مانند python:3.12-slim، پایتون درون /usr/local ساخته شده و هیچ نشانگر EXTERNALLY-MANAGED ندارد؛ بنابراین pip install به عنوان root روشی است که برای افزودن پکیجها در نظر گرفته شده و استفاده از venv در اینجا مزیت چندانی ندارد. در عوض، اگر FROM ubuntu:24.04 را بسازید، دوباره با externally-managed-environment درون ایمیج مواجه میشوید؛ به همان دلیلی که روی هاست وجود داشت: این مفسر توزیع است که فایل نشانگر همان توزیع را به همراه دارد.
بسیاری از ایمیجها همچنان از venv استفاده میکنند، زیرا ساخت چندمرحلهای (multi-stage build) را ساده میکند. مرحله builder پکیجها را در /opt/venv نصب میکند و مرحله runtime فقط همان دایرکتوری را کپی کرده و کامپایلرها را کنار میگذارد. مشکل فعالسازی (activate) همراه با آن منتقل میشود. یک خط RUN source /opt/venv/bin/activate فقط بر شل همان لایه از ساخت تأثیر میگذارد، بنابراین در زمان اجرا، کانتینر با مفسر سیستم شروع به کار کرده و خطای ModuleNotFoundError را صادر میکند. متغیر ENV PATH="/opt/venv/bin:$PATH" را تنظیم کنید یا به CMD مسیر مطلق /opt/venv/bin/gunicorn را بدهید. این همان باگ موجود در systemd است، فقط در فایلی متفاوت.
بنابراین، کانتینر مسئله مفسر را جایگزین میکند، زیرا ایمیج، مفسر و تمام محتویات زیرمجموعه آن را ثابت (pin) میکند. اما مسئله ثابتسازی نسخهها را جایگزین نمیکند. ایمیجی که از یک requirements.txt بدون نسخه ثابت ساخته شده باشد، ماه آینده نسخههای متفاوتی را resolve میکند؛ این یعنی تگ ایمیج قابل بازتولید است، اما فرآیند ساختی که آن را تولید کرده، خیر. یک فایل قفل (lockfile) مانند uv.lock یا یک فایل requirements که تمام نسخهها در آن قید شده باشد، همان چیزی است که این شکاف را پر میکند، چه در کانتینر و چه خارج از آن. و هنگامی که یک اپلیکیشن روی یک VPS تحت systemd اجرا میشود، کانتینر عمدتاً همین تصمیم را به یک Dockerfile منتقل میکند، چرا که systemd از قبل فرآیند شکستخورده را ریاستارت کرده و خروجی آن را در journal ثبت میکند. اجرای Docker روی یک VPS زمانی ارزش خود را نشان میدهد که بخواهید خودِ ایمیج ساختهشده، همان چیزی باشد که مستقر (deploy) میکنید.
FAQ
آیا میتوانم از pip install با فلگ --break-system-packages استفاده کنم؟
خیر، نه روی سروری که باید همیشه در حال اجرا باشد. این فلگ دقیقاً همان کاری را انجام میدهد که نامش میگوید: محافظت را حذف میکند و pip در مسیر /usr/local/lib/python3.12/dist-packages مینویسد که در اولویت بالاتری نسبت به دایرکتوری apt در sys.path قرار دارد. در نتیجه، نسخهٔ شما جایگزین نسخهٔ توزیع برای تمام اسکریپتهای سیستمی میشود که تحت /usr/bin/python3 اجرا میشوند. از آنجا که apt همچنان تصور میکند نسخهٔ خودش نصب است، هیچکس متوجه این تداخل نمیشود تا زمانی که سرویسی از کار بیفتد. در داخل یک image کانتینر که هر بار از صفر بازسازی میشود، آسیب به همان image محدود میماند و استفاده از آن قابلدفاع است. اما روی ماشینی که مدیریت میکنید، یک venv بسازید. این کار تنها با یک دستور انجام میشود.
محیط مجازی (virtual environment) باید در کجای سرور قرار بگیرد؟
در داخل دایرکتوری خودِ برنامه، با نام /srv/myapp/.venv، که مالکیت آن متعلق به یک کاربر deploy باشد و حساب کاربری سرویس فقط دسترسی خواندن و اجرا داشته باشد. برای هر برنامه یک venv جداگانه نگه دارید، زیرا استفاده از یک محیط مشترک باعث میشود ارتقای برنامهٔ اول، برنامهٔ دوم را دچار اختلال کند. پس از ساخت venv، آن را جابهجا یا کپی نکنید: تمام اسکریپتهای entry-point در دایرکتوری bin/ آن، دارای مسیر مطلق در خط shebang خود هستند؛ بنابراین venv جابهجاشده با خطای bad interpreter: No such file or directory مواجه میشود. در عوض، آن را حذف کرده و از روی requirements.txt دوباره بسازید.
چرا سرویس systemd من با خطای ModuleNotFoundError شکست میخورد؟
زیرا unit در حال اجرای مفسری است که متعلق به venv نیست. دستور systemctl cat myapp را اجرا کنید و ExecStart را بخوانید. این فایل باید به /srv/myapp/.venv/bin/python یا یک اسکریپت کنسول از همان دایرکتوری bin/ با مسیر مطلق اشاره کند. اجرای مستقیم activate در ExecStart کار نمیکند، زیرا ExecStart یک shell نیست و systemd با خطای status=203/EXEC، وضعیت Failed to locate executable source را گزارش میدهد. گزینهٔ Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin را اضافه کنید تا هر زیرفرآیندی که کد شما شروع میکند نیز ابزارهای venv را پیدا کند.
آیا باید بهجای venv و pip از uv استفاده کنم؟
زمانی از uv استفاده کنید که به یک lockfile نیاز دارید، زمان نصب آنقدر طولانی است که شما را آزار میدهد، یا به نسخهای از Python نیاز دارید که در توزیع شما موجود نیست. این ابزار یک venv معمولی میسازد، بنابراین unit مربوط به systemd و ساختار فایلها تغییری نمیکند و uv sync --frozen دقیقاً همان چیزی را نصب میکند که در lockfile ثبت شده است. اگر یک برنامهٔ واحد از طریق git با یک requirements.txt ثابت مستقر میشود و نصب آن در چند ثانیه به پایان میرسد، python3 -m venv کافی است و یک باینری کمتر برای بهروزرسانی روی سرور خواهید داشت.