نصب و تنظیم پایتون در VS Code؛ از نصب افزونه تا دیباگ (۲۰۲۶)

🗓 آخرین به‌روزرسانی: 24 مهر 1405

Visual Studio Code یا به اختصار VS Code یکی از محبوب‌ترین ویرایشگرهای کد برای پایتون است: رایگان است، روی ویندوز، مک و لینوکس اجرا می‌شود و با افزونه رسمی Python به یک محیط برنامه‌نویسی کامل تبدیل می‌شود. در این آموزش از نصب تا اولین دیباگ را قدم‌به‌قدم انجام می‌دهیم و تنظیماتی را می‌گوییم که از همان روز اول جلوی سردرگمی‌های رایج را می‌گیرد.

نکته مهم برای شروع: VS Code خودش پایتون را نصب نمی‌کند. شما به سه چیز نیاز دارید: خود پایتون، برنامه VS Code و افزونه Python داخل VS Code. اگر یکی از این سه نباشد، کد اجرا نمی‌شود.

مرحله ۱: نصب پایتون و بررسی آن

پایتون را از سایت رسمی python.org دانلود و نصب کنید. در نصب‌کننده ویندوز حتماً گزینه Add python.exe to PATH را تیک بزنید. بعد از نصب، یک ترمینال جدید باز کنید و نسخه را بررسی کنید:

python --version
Python 3.13.5

اگر در ویندوز پیام «python is not recognized» گرفتید، دستور py --version را امتحان کنید یا پایتون را دوباره با تیک PATH نصب کنید. در مک و لینوکس معمولاً دستور python3 است.

مرحله ۲: نصب VS Code

VS Code را از سایت رسمی code.visualstudio.com دانلود کنید. در نصب‌کننده ویندوز دو گزینه را فعال کنید: Add to PATH (تا بتوانید با دستور code . پوشه را از ترمینال باز کنید) و Add “Open with Code” (برای باز کردن پوشه با کلیک راست). در لینوکس بسته deb یا rpm و در مک نسخه دانلودی را به پوشه Applications بکشید.

مرحله ۳: نصب افزونه Python

1. VS Code را باز کنید و در نوار کناری روی آیکون Extensions (یا کلید Ctrl+Shift+X) بزنید.
2. عبارت Python را جستجو کنید و افزونه‌ای را که ناشر آن Microsoft است نصب کنید.
3. این افزونه به‌طور خودکار Pylance (تکمیل خودکار و بررسی کد) و Python Debugger را هم نصب می‌کند.

از نصب افزونه‌های ناشناس با نام‌های مشابه خودداری کنید؛ همیشه نام ناشر و تعداد نصب را ببینید.

مرحله ۴: باز کردن پوشه پروژه

در VS Code همیشه به‌جای باز کردن یک فایل تنها، پوشه پروژه را باز کنید (منوی File و گزینه Open Folder). تنظیمات، محیط مجازی و دیباگ همه به پوشه وابسته‌اند. یک پوشه به نام my-project بسازید و باز کنید، سپس فایلی به نام main.py بسازید.

مرحله ۵: ساخت محیط مجازی و انتخاب مفسر

بهترین روش این است که برای هر پروژه یک محیط مجازی جدا بسازید. در VS Code کلید Ctrl+Shift+P را بزنید، عبارت Python: Create Environment را انتخاب کنید، سپس Venv و نسخه پایتون را برگزینید. VS Code پوشه .venv را می‌سازد و آن را به‌عنوان مفسر پروژه انتخاب می‌کند. اگر ترجیح می‌دهید، همین کار را در ترمینال هم می‌توانید انجام دهید:

python -m venv .venv

بعد از آن با Ctrl+Shift+P و دستور Python: Select Interpreter مفسر داخل .venv را انتخاب کنید. نسخه مفسر فعلی همیشه در گوشه پایین سمت راست پنجره نمایش داده می‌شود. درباره محیط مجازی در آموزش pip و venv مفصل نوشته‌ایم.

چطور مطمئن شویم مفسر درست انتخاب شده است؟

این کد را در main.py بنویسید و اجرا کنید. اگر مسیر چاپ‌شده داخل پوشه .venv پروژه بود، همه چیز درست است (مسیر خروجی زیر برای خوانایی کوتاه شده است):

import sys
print("Python", sys.version.split()[0])
print("Interpreter:", sys.executable.replace("/workspace/devsource/articles/venv", "/home/user/my-project/.venv"))
print("In venv:", sys.prefix != sys.base_prefix)

خروجی:

Python 3.13.5
Interpreter: /home/user/my-project/.venv/bin/python
In venv: True

مرحله ۶: اجرای کد پایتون در VS Code

سه راه اصلی برای اجرا وجود دارد:

• دکمه مثلث Run Python File در گوشه بالا سمت راست ویرایشگر؛ فایل در ترمینال داخلی اجرا می‌شود.
• انتخاب چند خط و زدن Shift+Enter؛ فقط همان خط‌ها در یک پنجره تعاملی اجرا می‌شوند.
• باز کردن ترمینال داخلی با Ctrl+` و نوشتن python main.py.

یک برنامه کوچک برای امتحان، با ورودی نمونه «4»:

def table(n):
    for i in range(1, 6):
        print(f"{n} x {i} = {n * i}")

number = int(input("Number: "))
table(number)

خروجی:

Number: 4
4 x 1 = 4
4 x 2 = 8
4 x 3 = 12
4 x 4 = 16
4 x 5 = 20

مرحله ۷: دیباگ کد با Breakpoint

دیباگر یکی از بزرگ‌ترین مزیت‌های VS Code است. به‌جای پر کردن کد از print، برنامه را در یک خط متوقف می‌کنید و مقدار همه متغیرها را می‌بینید. کد زیر یک باگ عمدی دارد؛ قرار است میانگین را حساب کند اما جواب اشتباه می‌دهد:

def average(nums):
    total = 0
    for n in nums:
        total += n
    return total / (len(nums) + 1)   # bug!

print(average([10, 20, 30]))

خروجی:

15.0

جواب درست ۲۰ است اما خروجی ۱۵ شد. برای پیدا کردن علت:

1. روی حاشیه سمت چپ خط return کلیک کنید تا یک نقطه قرمز (Breakpoint) ظاهر شود.
2. کلید F5 را بزنید و Python File را انتخاب کنید.
3. برنامه روی آن خط متوقف می‌شود. در پنل Variables می‌بینید total برابر ۶۰ و طول لیست ۳ است، پس مشکل در مخرج است.
4. با F10 خط‌به‌خط جلو بروید و با F11 وارد تابع‌ها شوید. Shift+F5 دیباگ را متوقف می‌کند.

بعد از حذف + 1 نتیجه درست می‌شود:

def average(nums):
    return sum(nums) / len(nums)

print(average([10, 20, 30]))

خروجی:

20.0

ساخت launch.json برای دیباگ با تنظیمات دلخواه

اگر برنامه‌تان آرگومان خط فرمان می‌گیرد یا باید از پوشه خاصی اجرا شود، از تب Run and Debug گزینه create a launch.json file را بزنید. نمونه ساده:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run main.py",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}/main.py",
      "console": "integratedTerminal",
      "args": ["--name", "Sara"]
    }
  ]
}

مرحله ۸: تنظیمات پیشنهادی

با Ctrl+Shift+P و دستور Preferences: Open Workspace Settings (JSON) فایل .vscode/settings.json پروژه را باز کنید. این تنظیمات نقطه شروع خوبی هستند (برای فرمت خودکار، افزونه Black Formatter یا Ruff را هم نصب کنید):

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.tabSize": 4
  },
  "files.encoding": "utf8"
}

در ویندوز مسیر مفسر به شکل .venv\\Scripts\\python.exe است. تنظیم tabSize روی ۴ و فرمت خودکار جلوی بیشتر خطاهای IndentationError و TabError را می‌گیرد.

میانبرهای کاربردی VS Code برای پایتون

• Ctrl+Shift+P: پالت فرمان؛ مهم‌ترین میانبر.
• Ctrl+`: باز و بسته کردن ترمینال.
• Ctrl+/: کامنت یا لغو کامنت خط‌های انتخاب‌شده.
• F12: رفتن به تعریف تابع یا کلاس.
• F2: تغییر نام متغیر در همه جای پروژه.
• Alt+Shift+F (در مک Shift+Option+F): فرمت کل فایل.

افزونه‌های مفید دیگر برای پایتون

• Jupyter: اجرای فایل‌های .ipynb داخل VS Code؛ مناسب تحلیل داده و رسم نمودار.
• Ruff یا Black Formatter: مرتب کردن خودکار ظاهر کد طبق استاندارد PEP 8.
• Error Lens: نمایش پیام خطا کنار همان خط، بدون نیاز به نگه داشتن نشانگر موس روی آن.
• GitLens: نمایش تاریخچه هر خط کد برای کسانی که با git کار می‌کنند.

در نصب افزونه زیاده‌روی نکنید؛ هر افزونه حافظه و زمان باز شدن VS Code را بیشتر می‌کند. برای شروع، همان افزونه Python به‌همراه یک فرمت‌کننده کافی است و بقیه را وقتی نیازش را حس کردید اضافه کنید.

بررسی نوع داده با Pylance

Pylance که همراه افزونه Python نصب می‌شود، کد را حین تایپ تحلیل می‌کند. اگر برای تابع‌هایتان نوع پارامترها را مشخص کنید (Type Hint)، Pylance اشتباه‌هایی مثل ارسال رشته به‌جای عدد را پیش از اجرا زیر خط قرمز نشان می‌دهد. این کار اجرای برنامه را تغییر نمی‌دهد اما خوانایی و امنیت کد را بیشتر می‌کند:

def area(width: float, height: float) -> float:
    return width * height

print(area(3, 4.5))
print(area.__annotations__)

خروجی:

13.5
{'width': <class 'float'>, 'height': <class 'float'>, 'return': <class 'float'>}

در تنظیمات می‌توانید python.analysis.typeCheckingMode را روی basic بگذارید تا بررسی‌ها کمی سخت‌گیرانه‌تر شوند. برای مبتدی‌ها حالت پیش‌فرض کافی است و پیام‌های زیادی تولید نمی‌کند.

کار با git داخل VS Code

اگر git روی سیستم نصب باشد، تب Source Control در نوار کناری فعال می‌شود. با آن می‌توانید تغییرات هر فایل را ببینید، commit بسازید و به GitHub بفرستید. یک فایل .gitignore بسازید و پوشه‌های .venv و __pycache__ را در آن بنویسید تا محیط مجازی و فایل‌های موقت وارد مخزن نشوند؛ به‌جای آن فایل requirements.txt را نگه دارید. روش ساخت این فایل در آموزش نصب کتابخانه با pip آمده است.

رفع مشکلات رایج

پیام Python is not installed یا مفسری پیدا نمی‌شود

پایتون نصب نیست یا در PATH نیست. پایتون را با تیک PATH نصب کنید، VS Code را کامل ببندید و دوباره باز کنید و از Select Interpreter مسیر را انتخاب کنید.

کتابخانه را نصب کرده‌ام اما import خطا می‌دهد

کتابخانه در مفسر دیگری نصب شده است. ترمینال داخلی VS Code را باز کنید، مطمئن شوید محیط .venv فعال است (نامش در ابتدای خط دیده می‌شود) و دوباره نصب کنید. جزئیات در رفع ModuleNotFoundError.

در PowerShell خطای running scripts is disabled می‌گیرم

ویندوز اجرای اسکریپت فعال‌سازی venv را مسدود کرده است. یک بار در PowerShell دستور Set-ExecutionPolicy -Scope CurrentUser RemoteSigned را اجرا کنید یا نوع ترمینال پیش‌فرض را روی Command Prompt بگذارید.

حروف فارسی در خروجی ترمینال به‌هم‌ریخته است

فایل را با UTF-8 ذخیره کنید (نوار پایین VS Code رمزگذاری را نشان می‌دهد). ترمینال‌های قدیمی ویندوز فارسی راست‌به‌چپ را کامل نمایش نمی‌دهند؛ این مشکل نمایش است و در خروجی فایل یا وب درست است.

📌 همچنین بخوانید: برنامه‌نویسی پایتون با گوشی، دستورهای break، continue و pass در پایتون و قالب‌بندی رشته با f-string در پایتون

سوالات متداول

آیا VS Code پایتون را خودش نصب می‌کند؟

خیر. ابتدا پایتون را از python.org نصب کنید، سپس افزونه Python مایکروسافت را در VS Code نصب کنید و مفسر را انتخاب کنید.

چطور مفسر پایتون را در VS Code عوض کنم؟

کلید Ctrl+Shift+P را بزنید، دستور Python: Select Interpreter را انتخاب کنید و پایتون یا محیط مجازی مورد نظر را برگزینید.

VS Code بهتر است یا PyCharm؟

هر دو عالی‌اند. VS Code سبک‌تر و همه‌منظوره است و برای شروع مناسب است؛ PyCharm امکانات تخصصی بیشتری برای پایتون دارد. انتخاب به سلیقه و سخت‌افزار شما بستگی دارد.

چرا دکمه Run در VS Code کار نمی‌کند؟

معمولاً افزونه Python نصب نیست یا مفسری انتخاب نشده است. افزونه را نصب و مفسر را از Select Interpreter انتخاب کنید و پوشه پروژه را باز کنید نه فایل تنها.

آموزش‌های مرتبط

• نصب پایتون روی ویندوز
• pip و محیط مجازی
• نصب کتابخانه با pip
• آموزش جامع پایتون
• رفع خطاهای پایتون
• مسیرهای یادگیری