ساخت محیط مجازی پایتون در VS Code (ویندوز، مک و لینوکس)

جواب کوتاه: پوشه‌ی پروژه رو توی VS Code باز کن، ترمینال رو باز کن (منوی Terminal → New Terminal) و بزن:

python -m venv .venv

بعد فعالش کن (توی ویندوز .venv\Scripts\Activate.ps1، توی مک و لینوکس source .venv/bin/activate)، Ctrl+Shift+P رو بزن، Python: Select Interpreter رو اجرا کن و پایتونِ داخل .venv رو انتخاب کن. تموم شد: از این به بعد VS Code برای اجرا، دیباگ و ترمینال‌های جدید از همین محیط استفاده می‌کنه.

بقیه‌ی این راهنما دستورهای هر سیستم‌عامل و خطاهای رایج رو توضیح می‌ده؛ از جمله خطای PowerShell که تقریباً همه رو توی ویندوز گیر میندازه.

اصلاً چرا محیط مجازی؟

بدون محیط مجازی، هر pip install توی پایتونِ کل سیستم نصب می‌شه. دیر یا زود دو پروژه که نسخه‌های مختلفی از یه کتابخونه لازم دارن، همدیگه رو خراب می‌کنن. محیط مجازی فقط یه پوشه‌ست (.venv) با پایتون و پکیج‌های مخصوص خودش؛ برای هر پروژه یکی.

ویندوز

توی ترمینال VS Code (که پیش‌فرضش PowerShell است):

py -m venv .venv
.venv\Scripts\Activate.ps1

py لانچر پایتونه که با نصب‌کننده‌ی رسمی میاد؛ اگه python توی PATH باشه، python -m venv .venv هم کار می‌کنه. اگه فعال‌سازی درست انجام بشه، اول خط ترمینال (.venv) می‌بینی.

اگه به‌جای PowerShell از Command Prompt استفاده می‌کنی، با .venv\Scripts\activate.bat فعالش کن.

مک و لینوکس

python3 -m venv .venv
source .venv/bin/activate

توی دبیان و اوبونتو اگه خطای ensurepip is not available گرفتی، اول ماژول venv رو نصب کن:

sudo apt install python3-venv

انتخاب interpreter توی VS Code

فعال کردن توی ترمینال به‌تنهایی کافی نیست؛ VS Code هم باید بدونه برای اجرا و دیباگ از کدوم پایتون استفاده کنه.

Ctrl+Shift+P رو بزن (توی مک Cmd+Shift+P).
Python: Select Interpreter رو اجرا کن.
گزینه‌ای رو انتخاب کن که به .venv اشاره می‌کنه؛ معمولاً با برچسب Recommended.

از این به بعد ترمینال‌های جدیدِ این پروژه خودشون محیط رو فعال می‌کنن. اگه افزونه‌ی Python نصبه، دستور Python: Create Environment توی همون پنل، ساختن و انتخاب رو یه‌جا انجام می‌ده.

خطاهای رایج و راه‌حل‌شون

خطای «running scripts is disabled on this system»

این دقیقاً خطاییه که خودم توی ویندوز، موقع راه انداختن پروژه‌ی همین سایت، بهش خوردم. فعال‌سازی با این پیغام شکست می‌خوره:

.\.venv\Scripts\Activate.ps1 : File ...\Activate.ps1 cannot be loaded because
running scripts is disabled on this system.
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

محیط مجازیت هیچ ایرادی نداره. Execution Policy پاورشل توی ویندوز به‌صورت پیش‌فرض اجرای همه‌ی اسکریپت‌ها رو می‌بنده، و Activate.ps1 هم یه اسکریپته.

راه‌حل فقط برای همین پنجره (امن‌ترین؛ هیچ چیزی دائمی عوض نمی‌شه):

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
.venv\Scripts\Activate.ps1

-Scope Process فقط روی همین نشست PowerShell اثر داره؛ پنجره رو که ببندی، تنظیم برمی‌گرده سر جاش. می‌تونی هر دو رو توی یه خط هم بزنی، که من آخرش همین رو استفاده کردم:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned; .venv\Scripts\Activate.ps1

راه‌حل دائمی برای کاربر خودت (دسترسی ادمین لازم نیست):

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

RemoteSigned اجازه می‌ده اسکریپت‌های محلی اجرا بشن، ولی اسکریپت‌هایی که از اینترنت دانلود شدن هنوز امضا لازم دارن؛ تنظیم معمول برای سیستم برنامه‌نویسی همینه. فقط برای اینکه خطا بره، سراغ Unrestricted نرو.

VS Code محیط رو نمی‌بینه

اگه .venv توی Select Interpreter نیومد، گزینه‌ی Enter interpreter path رو بزن و این مسیر رو بده:

ویندوز: .venv\Scripts\python.exe
مک و لینوکس: .venv/bin/python

مطمئن شو پوشه‌ی پروژه رو باز کردی (File → Open Folder)، نه فقط یه فایل؛ VS Code دنبال .venv توی ریشه‌ی workspace می‌گرده.

پکیج توی پایتون اشتباه نصب می‌شه

pip install زدی، ولی کدت هنوز پکیج رو پیدا نمی‌کنه. ببین واقعاً کدوم پایتون فعاله:

python -c "import sys; print(sys.executable)"

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

python -m pip install requests

دو تا عادت کوچیک

.venv/ رو به .gitignore اضافه کن. محیط از روی فایل requirements دوباره ساخته می‌شه و هیچ‌وقت commit نمی‌شه.
وابستگی‌ها رو با python -m pip freeze > requirements.txt ذخیره کن و هر جای دیگه با python -m pip install -r requirements.txt دوباره بسازشون.

برای خارج شدن از محیط هم کافیه deactivate رو بزنی.