آموزش محیط مجازی پایتون (venv)؛ ساخت، فعالسازی و مدیریت
محیط مجازی پایتون چیست و چرا لازم است؟ #
فرض کنید روی دو پروژه کار میکنید: پروژهٔ قدیمی به Django 4.2 نیاز دارد و پروژهٔ جدید به Django 6. اگر هر دو را روی پایتون سیستم نصب کنید، فقط یکی میتواند همزمان نصب باشد. این همان «جهنم وابستگیها» است که هر برنامهنویس پایتون دیر یا زود تجربه میکند.
محیط مجازی (Virtual Environment) یک پوشهٔ ایزوله است که مفسر پایتون و پکیجهای مخصوص یک پروژه را جدا از بقیهٔ سیستم نگه میدارد. طبق مستندات رسمی venv، هر محیط مجازی مجموعهٔ مستقلی از پکیجها در پوشهٔ site-packages خودش دارد و بر پایتون پایهای که با آن ساخته شده سوار است.

مزایا:
- ایزوله بودن: هر پروژه نسخههای مخصوص خودش را دارد.
- تکرارپذیری: با یک فایل وابستگی، هر کسی همان محیط را میسازد.
- امنیت سیستم: پایتون سیستمعامل (که ابزارهای سیستم به آن وابستهاند) دست نمیخورد.
- پاکسازی آسان: حذف پروژه یعنی حذف یک پوشه.
یادداشت
در بسیاری از توزیعهای لینوکس جدید (مثل Debian و Ubuntu اخیر) اجرای pip install روی پایتون سیستم با خطای externally-managed-environment متوقف میشود. راهحل درست، استفاده از محیط مجازی است، نه --break-system-packages.
ساخت محیط مجازی با venv #
ماژول venv از پایتون ۳.۳ همراه خود پایتون است و نیاز به نصب ندارد:
# در پوشهٔ پروژه
python -m venv .venv
این دستور یک پوشه به نام .venv میسازد. نام .venv رایجترین قرارداد است و بیشتر ویرایشگرها (VS Code، PyCharm) آن را خودکار تشخیص میدهند.
نکته
در ویندوز اگر چند نسخه پایتون نصب دارید، از لانچر py استفاده کنید: py -3.14 -m venv .venv
فعالسازی محیط مجازی #

دستور فعالسازی به سیستمعامل و شل شما بستگی دارد:
source .venv/bin/activate
(.venv) $ which python
PS> .venv\Scripts\Activate.ps1
C:\project> .venv\Scripts\activate.bat
بعد از فعالسازی، نام محیط در ابتدای خط فرمان نمایش داده میشود و دستورات python و pip به نسخههای داخل محیط اشاره میکنند.
خطای Execution Policy در PowerShell #
اگر در ویندوز با خطای «running scripts is disabled on this system» روبهرو شدید، یک بار این دستور را اجرا کنید:
PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
غیرفعالسازی #
(.venv) $ deactivate
نصب پکیجها و فایل requirements.txt #
(.venv) $ pip install requests django
(.venv) $ pip list
(.venv) $ pip freeze > requirements.txt
فایل requirements.txt لیست دقیق پکیجها و نسخههاست. همتیمی شما محیط یکسان را اینطور میسازد:
python -m venv .venv
source .venv/bin/activate
(.venv) $ pip install -r requirements.txt
مهم
پوشهٔ .venv را هرگز در Git قرار ندهید. آن را به .gitignore اضافه کنید و فقط فایل وابستگیها را commit کنید. محیط مجازی قابل جابهجایی نیست و مسیرهای مطلق سیستم شما داخلش ذخیره شده است.
.venv/
__pycache__/
*.pyc
استفاده بدون فعالسازی #
فعالسازی فقط یک راحتی است. میتوانید مستقیماً مفسر داخل محیط را صدا بزنید؛ این روش در اسکریپتها، cron و سرویسها مطمئنتر است:
.venv/bin/python manage.py runserver
.venv/bin/pip install httpx
راه مدرنتر: uv #
ابزار uv ساخت محیط، نصب پکیج و قفل کردن نسخهها را بسیار سریعتر انجام میدهد:
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 #
- پوشهٔ پروژه را باز کنید.
Ctrl+Shift+Pو دستور Python: Select Interpreter را بزنید.- مفسر
.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 همین کارها را چند برابر سریعتر انجام میدهد.