آموزش محیط مجازی پایتون (venv)؛ ساخت، فعال‌سازی و مدیریت


محیط مجازی پایتون چیست و چرا لازم است؟ #

فرض کنید روی دو پروژه کار می‌کنید: پروژهٔ قدیمی به Django 4.2 نیاز دارد و پروژهٔ جدید به Django 6. اگر هر دو را روی پایتون سیستم نصب کنید، فقط یکی می‌تواند هم‌زمان نصب باشد. این همان «جهنم وابستگی‌ها» است که هر برنامه‌نویس پایتون دیر یا زود تجربه می‌کند.

محیط مجازی (Virtual Environment) یک پوشهٔ ایزوله است که مفسر پایتون و پکیج‌های مخصوص یک پروژه را جدا از بقیهٔ سیستم نگه می‌دارد. طبق مستندات رسمی venv، هر محیط مجازی مجموعهٔ مستقلی از پکیج‌ها در پوشهٔ site-packages خودش دارد و بر پایتون پایه‌ای که با آن ساخته شده سوار است.

سه حباب جدا که هرکدام پکیج‌های متفاوتی دارند

مزایا:

  • ایزوله بودن: هر پروژه نسخه‌های مخصوص خودش را دارد.
  • تکرارپذیری: با یک فایل وابستگی، هر کسی همان محیط را می‌سازد.
  • امنیت سیستم: پایتون سیستم‌عامل (که ابزارهای سیستم به آن وابسته‌اند) دست نمی‌خورد.
  • پاک‌سازی آسان: حذف پروژه یعنی حذف یک پوشه.

یادداشت

در بسیاری از توزیع‌های لینوکس جدید (مثل Debian و Ubuntu اخیر) اجرای pip install روی پایتون سیستم با خطای externally-managed-environment متوقف می‌شود. راه‌حل درست، استفاده از محیط مجازی است، نه --break-system-packages.

ساخت محیط مجازی با venv #

ماژول venv از پایتون ۳.۳ همراه خود پایتون است و نیاز به نصب ندارد:

bash
# در پوشهٔ پروژه
python -m venv .venv

این دستور یک پوشه به نام .venv می‌سازد. نام .venv رایج‌ترین قرارداد است و بیشتر ویرایشگرها (VS Code، PyCharm) آن را خودکار تشخیص می‌دهند.

نکته

در ویندوز اگر چند نسخه پایتون نصب دارید، از لانچر py استفاده کنید: py -3.14 -m venv .venv

فعال‌سازی محیط مجازی #

ترمینال با نشانگر سبز فعال‌سازی

دستور فعال‌سازی به سیستم‌عامل و شل شما بستگی دارد:

لینوکس و macOSbash
source .venv/bin/activate
(.venv) $ which python
ویندوز PowerShellpowershell
PS> .venv\Scripts\Activate.ps1
ویندوز CMDbat
C:\project> .venv\Scripts\activate.bat

بعد از فعال‌سازی، نام محیط در ابتدای خط فرمان نمایش داده می‌شود و دستورات python و pip به نسخه‌های داخل محیط اشاره می‌کنند.

خطای Execution Policy در PowerShell #

اگر در ویندوز با خطای «running scripts is disabled on this system» روبه‌رو شدید، یک بار این دستور را اجرا کنید:

powershell
PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

غیرفعال‌سازی #

bash
(.venv) $ deactivate

نصب پکیج‌ها و فایل requirements.txt #

bash
(.venv) $ pip install requests django
(.venv) $ pip list
(.venv) $ pip freeze > requirements.txt

فایل requirements.txt لیست دقیق پکیج‌ها و نسخه‌هاست. هم‌تیمی شما محیط یکسان را این‌طور می‌سازد:

bash
python -m venv .venv
source .venv/bin/activate
(.venv) $ pip install -r requirements.txt

مهم

پوشهٔ .venv را هرگز در Git قرار ندهید. آن را به .gitignore اضافه کنید و فقط فایل وابستگی‌ها را commit کنید. محیط مجازی قابل جابه‌جایی نیست و مسیرهای مطلق سیستم شما داخلش ذخیره شده است.

.gitignore
.venv/
__pycache__/
*.pyc

استفاده بدون فعال‌سازی #

فعال‌سازی فقط یک راحتی است. می‌توانید مستقیماً مفسر داخل محیط را صدا بزنید؛ این روش در اسکریپت‌ها، cron و سرویس‌ها مطمئن‌تر است:

bash
.venv/bin/python manage.py runserver
.venv/bin/pip install httpx

راه مدرن‌تر: uv #

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

bash
uv venv               # ساخت .venv
uv pip install django # نصب سریع
# یا مدیریت کامل پروژه:
uv init myproject
uv add django
uv run python manage.py runserver

uv run خودش محیط را می‌سازد، همگام می‌کند و دستور را داخل آن اجرا می‌کند، بدون نیاز به activate. برای آشنایی کامل، آموزش uv در تک‌کی را بخوانید.

مقایسهٔ ابزارها #

ابزار همراه پایتون سرعت فایل قفل مناسب برای
venv + pip بله معمولی ندارد (requirements) شروع کار، سادگی
virtualenv خیر سریع‌تر از venv ندارد پروژه‌های قدیمی
uv خیر بسیار سریع uv.lock پروژه‌های جدید
conda خیر کند environment.yml علم داده با وابستگی‌های غیرپایتونی

تنظیم در VS Code #

  1. پوشهٔ پروژه را باز کنید.
  2. Ctrl+Shift+P و دستور Python: Select Interpreter را بزنید.
  3. مفسر .venv را انتخاب کنید.

از این به بعد ترمینال داخلی VS Code محیط را خودکار فعال می‌کند.

خطاهای رایج و راه‌حل #

خطا علت راه‌حل
ModuleNotFoundError با اینکه نصب کرده‌اید پکیج روی پایتون دیگری نصب شده python -m pip install ... در محیط فعال
No module named venv در اوبونتو بستهٔ venv جدا است sudo apt install python3-venv
externally-managed-environment نصب روی پایتون سیستم ساخت و فعال‌سازی محیط مجازی
محیط بعد از جابه‌جایی پوشه کار نمی‌کند مسیرهای مطلق حذف و ساخت مجدد محیط

چک‌لیست #

  • برای هر پروژه یک محیط مجازی جدا بسازید.
  • نام .venv را به کار ببرید و آن را در .gitignore بگذارید.
  • وابستگی‌ها را در requirements.txt یا pyproject.toml ثبت کنید.
  • به‌جای pip تنها، از python -m pip استفاده کنید تا مطمئن شوید پکیج در محیط درست نصب می‌شود.
  • برای پروژه‌های جدید uv را امتحان کنید.

سؤالات متداول #

آیا باید برای هر پروژه محیط مجازی بسازم؟

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

تفاوت venv و virtualenv چیست؟

venv داخل پایتون است و برای بیشتر کاربردها کافی است. virtualenv یک پکیج خارجی قدیمی‌تر با قابلیت‌ها و سرعت بیشتر است.

چطور محیط مجازی را حذف کنم؟

کافی است deactivate کنید و پوشهٔ .venv را پاک کنید.

جمع‌بندی #

محیط مجازی ساده‌ترین و مهم‌ترین عادت حرفه‌ای در پایتون است: python -m venv .venv، فعال‌سازی، نصب پکیج‌ها و ثبت آن‌ها در فایل وابستگی. وقتی با این روند راحت شدید، uv همین کارها را چند برابر سریع‌تر انجام می‌دهد.

این پست چطور بود؟

پست‌های مرتبط