نصب کتابخانه در پایتون با pip؛ آنلاین، آفلاین و رفع خطاهای رایج
🗓 آخرین به‌روزرسانی:
بخش بزرگی از قدرت پایتون از کتابخانه‌های آن می‌آید: برای درخواست وب، رسم نمودار، کار با اکسل، ساخت ربات و هوش مصنوعی ده‌ها کتابخانه آماده وجود دارد. ابزار استاندارد نصب این کتابخانهها pip است. در این آموزش یاد می‌گیرید با pip کتابخانه را آنلاین و آفلاین نصب کنید، نسخه مشخص بخواهید، وابستگی‌های پروژه را در requirements.txt ثبت کنید و خطاهای رایج نصب را رفع کنید.
همه دستورها و نمونه‌کدها با پایتون 3.13.5 و pip 25.1.1 اجرا شده‌اند و خروجی‌ها، خروجی واقعی همان اجراها هستند (مسیرها برای خوانایی کوتاه شده‌اند).
pip چیست و کتابخانهها از کجا می‌آیند؟
pip مدیر بسته رسمی پایتون است و همراه نصب‌کننده‌های جدید پایتون نصب میشود. وقتی دستور pip install نام‌کتابخانه را اجرا میکنید، pip به مخزن عمومی PyPI (Python Package Index) وصل میشود، نسخه مناسب سیستم شما را پیدا میکند، آن را همراه همه کتابخانه‌هایی که به آن وابسته است دانلود و نصب میکند. کتابخانه نصب‌شده بعد از آن با import در کد شما در دسترس است. درباره تفاوت ماژول، پکیج و کتابخانه در آموزش ماژول و پکیج در پایتون توضیح داده‌ایم.
بررسی نصب بودن pip
در ترمینال (CMD یا PowerShell در ویندوز و Terminal در لینوکس و مک) این دستور را بزنید:
python -m pip --version
pip 25.1.1 from /home/user/project/env/lib/python3.13/site-packages/pip (python 3.13)پیشنهاد ما این است که همیشه به شکل python -m pip از pip استفاده کنید. این کار تضمین میکند کتابخانه دقیقاً برای همان پایتونی نصب شود که برنامه‌تان را با آن اجرا میکنید؛ مخصوصاً وقتی چند نسخه پایتون روی سیستم دارید. در ویندوز اگر python شناخته نشد، py -m pip را امتحان کنید.
نصب آنلاین کتابخانه با pip install
نصب آخرین نسخه
python -m pip install requestsنصب نسخه مشخص
گاهی آموزش یا پروژه‌ای به نسخه خاصی نیاز دارد. نسخه را با == مشخص کنید. خروجی واقعی این دستور نشان می‌دهد pip وابستگی‌ها را هم خودکار نصب کرده است:
python -m pip install requests==2.32.3
...
Successfully installed certifi-2026.7.22 charset-normalizer-3.5.2 idna-3.20 requests-2.32.3 urllib3-2.8.0می‌توانید بازه هم بدهید؛ مثلاً "requests>=2.30,<3" یعنی هر نسخه‌ای از ۲.۳۰ به بالا اما کمتر از ۳. در ویندوز و لینوکس عبارت دارای علامت بزرگ‌تر و کوچک‌تر را داخل گیومه بگذارید تا ترمینال آن را به‌عنوان تغییر مسیر خروجی تفسیر نکند.
بررسی نصب از داخل پایتون
بعد از نصب، با این کد مطمئن شوید کتابخانه از همان مفسری که اجرا میکنید در دسترس است و نسخه‌اش را ببینید:
import sys
from importlib.metadata import version, PackageNotFoundError
print("Python:", sys.version.split()[0])
for pkg in ["requests", "matplotlib", "not-installed-lib"]:
try:
print(f"{pkg}: {version(pkg)}")
except PackageNotFoundError:
print(f"{pkg}: NOT installed")خروجی:
Python: 3.13.5
requests: 2.34.2
matplotlib: 3.11.2
not-installed-lib: NOT installedبه‌روزرسانی، مشاهده و حذف کتابخانه
python -m pip install --upgrade requestsکتابخانه را به آخرین نسخه می‌برد.python -m pip install --upgrade pipخود pip را به‌روز میکند.python -m pip show requestsنسخه، توضیح و محل نصب را نشان می‌دهد.python -m pip listفهرست همه کتابخانه‌های نصب‌شده را می‌دهد.python -m pip uninstall requestsکتابخانه را حذف میکند (با-yبدون پرسش).
خروجی واقعی pip list در یک محیط تازه بعد از نصب requests:
Package Version
------------------ ---------
certifi 2026.7.22
charset-normalizer 3.5.2
idna 3.20
pip 25.1.1
requests 2.32.3
urllib3 2.8.0نصب کتابخانه در محیط مجازی (venv)
اگر همه کتابخانهها را در پایتون اصلی سیستم نصب کنید، دیر یا زود دو پروژه به دو نسخه متفاوت از یک کتابخانه نیاز پیدا میکنند و تداخل پیش می‌آید. راه‌حل استاندارد، ساخت محیط مجازی جداگانه برای هر پروژه است:
python -m venv env
# Windows:
env\Scripts\activate
# Linux / macOS:
source env/bin/activate
python -m pip install requestsبعد از فعال شدن، نام محیط در ابتدای خط ترمینال دیده میشود و هر pip install فقط در همان پوشه اثر می‌گذارد. توضیح کامل در آموزش pip و محیط مجازی venv آمده است. در لینوکس‌های جدید، نصب مستقیم در پایتون سیستم با خطای externally-managed-environment متوقف میشود و استفاده از venv عملاً اجباری است.
ثبت وابستگی‌ها با requirements.txt
وقتی پروژه را برای دوستتان می‌فرستید یا روی سرور می‌برید، باید بدانید دقیقاً چه کتابخانه‌هایی با چه نسخه‌ای لازم است. دستور freeze این فهرست را می‌سازد:
python -m pip freeze > requirements.txtمحتوای واقعی فایل ساخته‌شده در محیط آزمایشی ما:
certifi==2026.7.22
charset-normalizer==3.5.2
colorama==0.4.6
idna==3.20
requests==2.32.3
urllib3==2.8.0در سیستم دیگر، همه را با یک دستور نصب کنید:
python -m pip install -r requirements.txtنصب آفلاین کتابخانه پایتون
اگر روی سیستمی کار میکنید که اینترنت ندارد یا اتصال آن به PyPI ناپایدار است، می‌توانید کتابخانه را روی سیستم دیگری دانلود کنید و فایل‌ها را با فلش یا هر روش دیگری منتقل کنید. فایلهای نصبی پایتون معمولاً با پسوند .whl (Wheel) هستند.
مرحله ۱: دانلود روی سیستم دارای اینترنت
python -m pip download colorama -d wheels
Saved ./wheels/colorama-0.4.6-py2.py3-none-any.whl
Successfully downloaded coloramaبرای کل پروژه هم می‌توانید python -m pip download -r requirements.txt -d wheels را اجرا کنید تا همه وابستگی‌ها یکجا دانلود شوند.
مرحله ۲: نصب روی سیستم بدون اینترنت
python -m pip install --no-index --find-links wheels colorama
Installing collected packages: colorama
Successfully installed colorama-0.4.6گزینه --no-index به pip می‌گوید سراغ اینترنت نرود و --find-links پوشه فایل‌ها را معرفی میکند.
نکته مهم درباره سازگاری فایل whl
نام فایل wheel نشان می‌دهد برای چه سیستمی ساخته شده است. py3-none-any یعنی کتابخانه خالص پایتونی است و روی همه سیستم‌ها کار میکند. اما کتابخانه‌هایی مثل numpy فایل‌هایی با نام‌هایی مثل cp313-win_amd64 دارند؛ یعنی فقط برای پایتون ۳.۱۳ روی ویندوز ۶۴ بیتی. پس فایل را روی سیستمی با همان نسخه پایتون و همان سیستمعامل دانلود کنید، یا با گزینه‌های --platform و --python-version همراه با --only-binary=:all: نسخه مقصد را مشخص کنید.
نصب کتابخانه در VS Code و Jupyter
در VS Code ترمینال داخلی (منوی Terminal و گزینه New Terminal) را باز کنید. اگر محیط مجازی را به‌عنوان مفسر انتخاب کرده باشید، VS Code معمولاً آن را خودکار در ترمینال فعال میکند. پیش از نصب، نام مفسر انتخاب‌شده را در نوار پایین پنجره ببینید تا کتابخانه در جای درست نصب شود. راهنمای کامل این تنظیمات در آموزش نصب و تنظیم پایتون در VS Code خواهد آمد.
در Jupyter Notebook دستور ویژه %pip install نام‌کتابخانه را در یک سلول اجرا کنید. علامت درصد باعث میشود نصب برای همان کرنلی انجام شود که نوت‌بوک با آن اجرا میشود؛ استفاده از !pip گاهی کتابخانه را در پایتون دیگری نصب میکند و بعد از نصب هم import شکست می‌خورد.
نصب از منابع دیگر
- از فایل محلی:
python -m pip install ./package-1.0-py3-none-any.whlیک فایل wheel مشخص را نصب میکند. - از پوشه پروژه در حالت توسعه:
python -m pip install -e .پروژه خودتان را طوری نصب میکند که تغییرات کد بلافاصله اعمال شود. - از مخزن git:
python -m pip install git+https://github.com/user/repo.gitکد را مستقیم از مخزن نصب میکند؛ فقط از مخزن‌هایی که به آن‌ها اعتماد دارید.
نکته امنیتی: هر پکیجی را نصب نکنید
PyPI مخزنی باز است و هر کسی می‌تواند در آن پکیج منتشر کند. گاهی افراد سودجو پکیج‌هایی با نامی شبیه کتابخانه‌های معروف منتشر میکنند تا کسی که نام را اشتباه تایپ میکند، کد مخرب نصب کند. پیش از نصب کتابخانه‌ای که نمی‌شناسید، صفحه آن را در pypi.org ببینید: تاریخ انتشار، تعداد نسخه‌ها، لینک مستندات و مخزن کد نشانه‌های خوبی از اعتبار آن هستند. نام را با دقت تایپ کنید و دستورهای نصب را از منابع ناشناس کپی نکنید.
کتابخانه‌های پرکاربرد برای شروع
requestsبرای ارسال درخواست HTTP و کار با API.matplotlibبرای رسم نمودار.pandasبرای کار با جدول‌ها و فایلهای CSV و اکسل.pygameبرای ساخت بازی‌های دوبعدی ساده.python-telegram-botبرای ساخت ربات تلگرام؛ آموزش آن را در ساخت ربات تلگرام با پایتون ببینید.
رفع خطاهای رایج pip
خطای pip is not recognized
یعنی ویندوز مسیر pip را نمی‌شناسد. ساده‌ترین راه استفاده از python -m pip یا py -m pip است. راه‌حل کامل، از جمله اضافه کردن پایتون به PATH، در آموزش رفع خطای pip is not recognized آمده است.
خطای No matching distribution found
خروجی واقعی وقتی نام کتابخانه اشتباه است:
python -m pip install nosuchpkg-xyz-123
ERROR: Could not find a version that satisfies the requirement nosuchpkg-xyz-123 (from versions: none)
ERROR: No matching distribution found for nosuchpkg-xyz-123دلیل‌های رایج: نام اشتباه (مثلاً نام پکیج OpenCV در pip opencv-python است نه cv2)، نبودن نسخه سازگار با نسخه پایتون شما، یا قطع یا محدود بودن اتصال به PyPI. نام دقیق را در سایت pypi.org جستجو کنید و نسخه پایتونتان را بررسی کنید.
کتابخانه نصب شده اما ModuleNotFoundError می‌گیرم
تقریباً همیشه کتابخانه در پایتون دیگری نصب شده است؛ مثلاً در پایتون سیستم، در حالی که VS Code از محیط مجازی استفاده میکند. کد بررسی بالا را اجرا کنید و مسیر sys.executable را با مسیر pip مقایسه کنید. جزئیات در رفع ModuleNotFoundError آمده است.
import sys
print(sys.executable.replace("/workspace/devsource/articles", "/home/user/project"))خروجی:
/home/user/project/venv/bin/pythonخطای Permission denied یا دسترسی
در ویندوز ترمینال را با دسترسی ادمین اجرا نکنید؛ به‌جایش از محیط مجازی یا گزینه --user استفاده کنید. در لینوکس و مک هرگز pip را با sudo اجرا نکنید چون ممکن است پایتون سیستمعامل را خراب کند.
دانلود خیلی کند است یا قطع میشود
گزینه --timeout 60 زمان انتظار را بیشتر میکند و --retries 10 تعداد تلاش دوباره را. اگر بارها قطع شد، روش آفلاین بالا را به کار ببرید: یک بار در زمانی که اتصال پایدار است فایل‌ها را دانلود و بعد بدون اینترنت نصب کنید.
📌 همچنین بخوانید: نصب و تنظیم پایتون در VS Code، برنامه‌نویسی پایتون با گوشی و دستورهای break، continue و pass در پایتون
سوالات متداول
چطور یک کتابخانه را در پایتون نصب کنم؟
در ترمینال دستور python -m pip install و نام کتابخانه را اجرا کنید؛ مثلاً python -m pip install requests. بهتر است این کار را داخل یک محیط مجازی انجام دهید.
آیا میشود کتابخانه پایتون را بدون اینترنت نصب کرد؟
بله. روی یک سیستم دارای اینترنت با pip download فایلهای whl را دانلود کنید و روی سیستم مقصد با pip install –no-index –find-links نصب کنید. نسخه پایتون و سیستمعامل باید سازگار باشد.
فرق pip و python -m pip چیست؟
هر دو pip را اجرا میکنند، اما python -m pip تضمین میکند pip متعلق به همان پایتونی باشد که با آن برنامه را اجرا میکنید و جلوی نصب در پایتون اشتباه را میگیرد.
requirements.txt چیست؟
فایلی متنی شامل فهرست کتابخانهها و نسخههای پروژه است که با pip freeze ساخته میشود و با pip install -r در سیستم دیگر همه را یکجا نصب میکند.
آموزش‌های مرتبط
- pip و محیط مجازی venv
- ماژول و پکیج در پایتون
- رفع ModuleNotFoundError
- آموزش جامع پایتون
- رفع خطاهای پایتون
- مسیرهای یادگیری