پایتون، pip و محیط‌های مجازی روی VPS با Ubuntu 24.04

Ubuntu 24.04 با Python 3.12 عرضه می‌شود، اما نصب بسته با pip به‌صورت مستقیم اکنون با خطای «externally-managed-environment» شکست می‌خورد. راه‌حل، جدا کردن هر پروژه در محیط مجازی مخصوص خودش است. این راهنما نشان می‌دهد چگونه VPS Linux Infrawire را آماده کنید، وابستگی‌ها را درست مدیریت کنید و برنامه را به‌صورت سرویس systemd پایدار نگه دارید.

📋 پیش‌نیازها

یک VPS با Ubuntu 24.04 یا Debian 12 و دسترسی SSH با کاربر root (آی‌پی و گذرواژه root در بخش مشتریان شما موجود است)
یک پروژه پایتون یا یک اسکریپت ساده برای آزمایش
آشنایی پایه با خط فرمان

1. نصب Python 3، pip و venv

Python 3 معمولاً از قبل نصب است، اما pip و ماژول venv بسته‌های جداگانه‌ای هستند.

Bash
1apt update
2apt install -y python3 python3-pip python3-venv python3-dev build-essential
3python3 --version
4pip3 --version

2. درک خطای PEP 668

اجرای pip install requests با کاربر root روی Ubuntu 24.04 یا Debian 12 این پیام را نشان می‌دهد:

TEXT
error: externally-managed-environment

این محافظت (PEP 668) مانع می‌شود pip فایل‌های تحت مدیریت apt را بازنویسی کند و ابزارهای سیستم را خراب کند. آن را با --break-system-packages دور نزنید. یکی از سه روش تمیز زیر را به کار ببرید.

3. ساخت یک محیط مجازی

محیط مجازی یک نسخه خصوصی از Python و pip برای یک پروژه است.

Bash
1mkdir -p /opt/myapp && cd /opt/myapp
2python3 -m venv venv
3source venv/bin/activate
4pip install --upgrade pip
5pip install requests flask gunicorn

اکنون اعلان خط فرمان با (venv) شروع می‌شود. با deactivate از محیط خارج شوید.

4. مدیریت وابستگی‌ها با requirements.txt

نسخه‌های دقیق را ثبت کنید تا بتوانید پروژه را روی سرور دیگر دقیقاً مثل قبل بازسازی کنید.

Bash
1pip freeze > requirements.txt
2# روی یک ماشین تازه
3python3 -m venv venv
4source venv/bin/activate
5pip install -r requirements.txt

5. نصب ابزارهای خط فرمان با pipx

برای ابزارهای مستقل (httpie، yt-dlp، black و غیره)، pipx به هرکدام یک محیط مجازی پنهان جداگانه می‌دهد و دستور را به‌صورت سراسری در دسترس قرار می‌دهد.

Bash
1apt install -y pipx
2pipx ensurepath
3pipx install httpie

پس از آن یک پوسته جدید باز کنید تا PATH به‌روزشده بارگذاری شود. برای کتابخانه‌ای که بسته Debian دارد، apt install python3-requests هم گزینه‌ای معتبر است.

6. اجرای برنامه به‌صورت سرویس systemd

یک کاربر اختصاصی بدون دسترسی ویژه بسازید، سپس یک unit بنویسید که مفسر محیط مجازی را اجرا کند (اینجا Gunicorn که شیء Flask با نام app را در app.py سرو می‌کند).

Bash
1useradd --system --home /opt/myapp --shell /usr/sbin/nologin myapp
2chown -R myapp:myapp /opt/myapp

فایل /etc/systemd/system/myapp.service را بسازید:

INI
1[Unit]
2Description=My Python application
3After=network.target
4
5[Service]
6User=myapp
7WorkingDirectory=/opt/myapp
8ExecStart=/opt/myapp/venv/bin/gunicorn --bind 127.0.0.1:8000 app:app
9Restart=on-failure
10RestartSec=5
11
12[Install]
13WantedBy=multi-user.target

Bash
1systemctl daemon-reload
2systemctl enable --now myapp

برای انتشار برنامه در اینترنت، یک پراکسی معکوس مانند nginx جلوی پورت 8000 قرار دهید.

✅ بررسی

Bash
1which python   # هنگام فعال بودن باید به داخل /opt/myapp/venv اشاره کند
2pip list
3systemctl status myapp --no-pager
4journalctl -u myapp -n 50 --no-pager
5curl -I http://127.0.0.1:8000

🔧 عیب‌یابی

The virtual environment was not created successfully because ensurepip is not available : بسته venv نصب نیست. آن را با apt install python3-venv (یا python3.12-venv) نصب کنید و دستور را دوباره اجرا کنید.

status=203/EXEC در systemd : مسیر ExecStart اشتباه است یا فایل برای کاربر سرویس قابل اجرا نیست. با ls -l /opt/myapp/venv/bin/gunicorn و مالکیتی که قبلاً تنظیم کردید بررسی کنید.

ModuleNotFoundError فقط زیر systemd : سرویس به‌جای محیط مجازی از پایتون سیستم استفاده می‌کند. در ExecStart همیشه /opt/myapp/venv/bin/python یا فایل اجرایی داخل venv/bin را فراخوانی کنید.

pip: command not found : از python3 -m pip استفاده کنید یا ابتدا محیط مجازی را فعال کنید.

🎉 پروژه‌های پایتون شما اکنون ایزوله، تکرارپذیر و به‌صورت یک سرویس قابل اعتماد در حال اجرا هستند!