نصب کتابخانه با pip و ساخت محیط مجازی venv در پایتون

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

برای استفاده از کتابخانه‌های خارجی پایتون باید آن‌ها را با pip نصب کنیم؛ اما نصب همه پکیج‌ها در محیط اصلی سیستم می‌تواند باعث تداخل نسخه‌ها و خراب‌شدن پروژه‌ها شود. روش استاندارد این است که برای هر پروژه یک محیط مجازی مستقل با venv بسازیم.

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

pip چیست؟

pip ابزار استاندارد نصب و مدیریت پکیج‌های پایتون است. بیشتر پکیج‌ها از مخزن عمومی PyPI دریافت می‌شوند. برای نمونه، کتابخانه requests را می‌توانیم با دستور زیر نصب کنیم:

python -m pip install requests

پس از نصب، کتابخانه مانند هر ماژول دیگری قابل استفاده است:

import requests

print(requests.__version__)

چرا از python -m pip استفاده کنیم؟

ممکن است چند نسخه پایتون روی سیستم نصب باشد و دستور ساده pip به مفسر دیگری متصل شود. الگوی python -m pip مشخص می‌کند pip با همان نسخه پایتونی اجرا شود که برنامه را اجرا می‌کند.

در ویندوز می‌توانید از لانچر py استفاده کنید:

py -m pip --version

در macOS و Linux معمولاً دستور زیر مناسب است:

python3 -m pip --version

در ادامه، هرجا دستور python نوشته شده است، در صورت نیاز آن را با py یا python3 جایگزین کنید.

بررسی و به‌روزرسانی pip

برای مشاهده نسخه pip:

python -m pip --version

برای به‌روزرسانی آن:

python -m pip install --upgrade pip

اگر pip در یک نصب رسمی پایتون در دسترس نبود، می‌توانید ابزار داخلی زیر را امتحان کنید:

python -m ensurepip --upgrade

دستورهای اصلی pip

نصب پکیج

python -m pip install requests

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

python -m pip list

مشاهده جزئیات یک پکیج

python -m pip show requests

به‌روزرسانی پکیج

python -m pip install --upgrade requests

حذف پکیج

python -m pip uninstall requests

نصب نسخه مشخص یک کتابخانه

گاهی یک پروژه فقط با نسخه مشخصی از یک پکیج سازگار است:

python -m pip install requests==2.32.3

می‌توانیم محدوده نسخه نیز تعیین کنیم:

python -m pip install "requests>=2.31,<3"

چرا نصب سراسری پکیج‌ها مشکل‌ساز است؟

فرض کنید پروژه اول به نسخه 4 یک کتابخانه و پروژه دوم به نسخه 5 همان کتابخانه نیاز دارد. اگر همه پکیج‌ها در محیط اصلی نصب شوند، نسخه جدید ممکن است جای نسخه قبلی را بگیرد و یکی از پروژه‌ها از کار بیفتد.

محیط مجازی این مشکل را حل می‌کند؛ زیرا هر پروژه مجموعه مستقل پکیج‌ها و نسخه‌های خود را دارد.

محیط مجازی venv چیست؟

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

my_project/
├── .venv/
├── main.py
└── requirements.txt

پوشه .venv فقط به همان پروژه مربوط است و نصب پکیج در آن روی پروژه‌های دیگر اثر نمی‌گذارد.

ساخت محیط مجازی در ویندوز

ابتدا وارد پوشه پروژه شوید و اجرا کنید:

py -m venv .venv

برای فعال‌سازی در PowerShell:

.venv\Scripts\Activate.ps1

برای فعال‌سازی در Command Prompt:

.venv\Scripts\activate.bat

ساخت محیط مجازی در macOS و Linux

python3 -m venv .venv

برای فعال‌سازی در Bash یا Zsh:

source .venv/bin/activate

پس از فعال‌سازی، معمولاً عبارت (.venv) در ابتدای خط فرمان نمایش داده می‌شود.

چگونه فعال‌بودن محیط را بررسی کنیم؟

در ویندوز:

where python
python -m pip --version

در macOS و Linux:

which python
python -m pip --version

مسیر نمایش‌داده‌شده باید به پوشه .venv پروژه اشاره کند.

در خود پایتون نیز می‌توان مسیر مفسر را مشاهده کرد:

import sys

print(sys.executable)
print(sys.prefix)
print(sys.base_prefix)

در یک محیط مجازی، معمولاً مقدار sys.prefix با sys.base_prefix متفاوت است.

نصب کتابخانه داخل محیط مجازی

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

python -m pip install requests

سپس یک فایل با نام main.py بسازید:

import requests

print("Requests version:", requests.__version__)
print("Package imported successfully")

برنامه را اجرا کنید:

python main.py

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

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

خروج و ورود دوباره به محیط مجازی

برای غیرفعال‌کردن محیط در همه سیستم‌عامل‌ها:

deactivate

بستن ترمینال نیز محیط را غیرفعال می‌کند؛ اما پوشه محیط حذف نمی‌شود. دفعه بعد کافی است وارد پوشه پروژه شوید و دستور فعال‌سازی را دوباره اجرا کنید.

فایل requirements.txt چیست؟

این فایل فهرست وابستگی‌های پروژه و نسخه آن‌ها را نگه می‌دارد. به کمک آن می‌توان محیط پروژه را روی یک سیستم دیگر بازسازی کرد.

برای ساخت فایل:

python -m pip freeze > requirements.txt

نمونه محتوا:

requests==2.32.3
urllib3==2.2.3
certifi==2024.8.30

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

نصب وابستگی‌ها از requirements.txt

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

python -m pip install -r requirements.txt

چرخه معمول راه‌اندازی پروژه به این ترتیب است:

1. ورود به پوشه پروژه
2. ساخت محیط مجازی
3. فعال‌سازی محیط
4. به‌روزرسانی pip
5. نصب فایل requirements
6. اجرای برنامه

نمونه کامل در ویندوز

cd my_project
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python main.py

نمونه کامل در macOS و Linux

cd my_project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python main.py

آیا پوشه .venv را در Git ذخیره کنیم؟

خیر. این پوشه معمولاً حجم زیادی دارد، به سیستم‌عامل و مسیرهای محلی وابسته است و از روی فایل requirements.txt قابل بازسازی است.

در فایل .gitignore این خط را اضافه کنید:

.venv/

حذف و بازسازی محیط مجازی

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

python -m venv .venv
python -m pip install -r requirements.txt

محیط مجازی را میان سیستم‌ها کپی نکنید؛ بازسازی آن مطمئن‌تر است.

خطاهای رایج

pip نصب می‌کند اما import انجام نمی‌شود

احتمالاً pip و Python به دو محیط متفاوت متصل هستند. این دستورها را بررسی کنید:

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

دستور python پیدا نمی‌شود

در ویندوز از py و در macOS یا Linux از python3 استفاده کنید.

محیط مجازی فعال است ولی ویرایشگر خطا می‌دهد

مفسر پایتون پروژه را در تنظیمات ویرایشگر روی فایل داخل .venv قرار دهید.

پکیج در محیط اشتباه نصب شده است

محیط درست را فعال کنید و نصب را با python -m pip تکرار کنید.

تفاوت pip، venv و pipx

نکات حرفه‌ای

• برای هر پروژه یک محیط مجازی جداگانه بسازید.
• از نام رایج .venv استفاده کنید.
• پیش از نصب، مسیر مفسر را بررسی کنید.
• به‌جای دستور pip تنها، از python -m pip استفاده کنید.
• پوشه محیط مجازی را در Git ثبت نکنید.
• وابستگی‌ها را در فایل requirements.txt نگه دارید.
• پکیج‌های ناشناس را بدون بررسی منبع نصب نکنید.

تمرین‌های درس

1. پروژه‌ای با نام library_test بسازید و برای آن محیط .venv ایجاد کنید.
2. کتابخانه Requests را نصب و نسخه آن را نمایش دهید.
3. فهرست وابستگی‌ها را در requirements.txt ذخیره کنید.
4. محیط را حذف و با فایل requirements دوباره بسازید.
5. مسیر sys.executable را قبل و بعد از فعال‌سازی مقایسه کنید.

جمع‌بندی

در این درس با pip برای نصب، مشاهده، ارتقا و حذف پکیج‌ها آشنا شدیم. سپس با venv محیط مجازی ساختیم، روش فعال‌سازی آن را در ویندوز، macOS و Linux یاد گرفتیم و وابستگی‌ها را با فایل requirements.txt مدیریت کردیم.

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

📌 همچنین بخوانید: بازار کار پایتون در ایران، دستورهای break، continue و pass در پایتون و ساخت ربات تلگرام با پایتون