راهنمای جامع ابزار pip

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

مقدمه

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

آشنایی با pip در پایتون

ابزار pip در پایتون، پکیج منیجر رسمی زبان برنامه‌نویسی پایتون برای نصب کتابخانه‌ها و ماژول‌ها است. کلمه pip مخفف Pip Installs Packages است و این ابزار به صورت پیش‌فرض همراه بسیاری از نسخه‌های پایتون نصب می‌شود. به صورت کلی می‌توان گفت pip امکان دانلود پکیج‌ها از مخزن رسمی پایتون یعنی PyPI را فراهم می‌کند.

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

پیش‌نیازهای ابزار pip

پیش از ادامه آموزش، ابتدا اطمینان حاصل کنید که پایتون روی سیستم شما نصب است:

# in Windows
py --version

# in Linux and MacOS
python3 --version

همچنین مطمئن شوید که ابزار pip نیز بر روی سیستم شما از قبل نصب شده است:

# in Windows
py -m pip --version

# in Linux and MacOS
python3 -m pip --version

در صورتی که pip نصب نبود، می‌توانید با دستور زیر اقدام به نصب آن نمایید:

# in Windows
py -m ensurepip --default-pip

# in Linux and MacOS
python3 -m ensurepip --default-pip

توصیه می‌شود همیشه قبل از شروع کار با pip، آن را به روزرسانی کنید تا از آخرین قابلیت‌های آن بهره‌مند شوید:

# in Windows
py -m pip install --upgrade pip

# in Linux and MacOS
python3 -m pip install --upgrade pip

آشنایی با محیط مجازی

فرض کنید شما برنامه‌ای دارید که نیازمند نسخه 1 از کتابخانه فرضی LibFoo است اما برنامه دیگری به نسخه 2 این کتابخانه نیاز دارد. چطور می‌توانید این دو برنامه را همزمان روی یک سیستم داشته باشید؟ یا ممکن است شما کاربر یک هاست اشتراکی باشید. طبیعتاً‌ ادمین سرور به شما اجازه نمی‌دهد هر ماژول یا کتابخانه پایتونی را بر روی کل فضای هاست نصب کنید! حتی گاهی اوقات برخی برنامه‌های قدیمی داریم که فقط با یک نسخه قدیمی از ماژول‌ها کار می‌کنند و اگر آن ماژول‌ها آپدیت شوند، عملکرد برنامه مختل می‌شود.

محیط مجازی یا Virtual Environment یک فضای نیمه ایزوله برای هر پروژه پایتون ایجاد می‌کند تا پکیج‌های نصب‌شده تنها برای همان پروژه استفاده شوند و با سایر پروژه‌ها تداخل نداشته باشند. در پایتون، ابزار استاندارد ایجاد محیط مجازی، ماژول venv است اما ابزارهای شخص ثالث مانند ماژول virtualenv نیز وجود دارند که عملکردی مشابه venv دارند.

نکته تکمیلی ۱: از نسخه 3.3 به بعد پایتون، همراه با نصب هسته پایتون، ماژول venv نیز همراه آن نصب می‌شود. در نسخه‌های جدید پایتون (از 3.12 به بعد)، هر زمان که شما از ماژول venv برای ساخت محیط مجازی استفاده می‌کنید، به صورت پیش‌فرض ابزار pip نیز درون محیط مجازی جدید شما نصب می‌شود.

نکته تکمیلی ۲: ماژول virtualenv می‌بایست به صورت جداگانه نصب شود. هر زمان که شما با استفاده از این ماژول اقدام به ساخت یک محیط مجازی کنید، پکیج‌های pip و setuptools و wheel به صورت پیش‌فرض درون آن نصب خواهند شد.

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

# in Windows
python -m venv venv

# in Linux and MacOS
python3 -m venv venv

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

# in Windows
venv\Scripts\activate

# in Linux and MacOS
source venv/bin/activate

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

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

کاربردهای پایه‌ای ابزار pip

۱) نصب و حذف پکیج‌ها

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

pip install requests

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

pip install "requests==2.31.0"

همچنین می‌توانید مشخص کنید که پکیج مدنظر حداقل با چه نسخه‌ای و بالاتر از آن سازگار باشد:

pip install "requests~=2.28.0"

در این مثال، آن نسخه‌ای از پکیج requests نصب می‌شود که با نسخه 2.28.0 و بالاتر از آن سازگار باشد.

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

اگر دسترسی ادمین ندارید یا نمی‌خواهید پکیج را برای همه کاربران سیستم نصب کنید، می‌توانید نصب پکیج را با استفاده از سوییچ user، فقط برای کاربر جاری انجام دهید:

pip install --user requests

تذکر: توجه داشته باشید که وقتی داخل محیط مجازی هستید، سوئیچ user تأثیری ندارد و همه پکیج‌ها در محیط مجازی نصب می‌شوند!

برای حذف پکیج به وسیله pip کافیست از دستور uninstall استفاده کنید:

pip uninstall requests

۲) به‌روزرسانی پکیج‌های نصب شده

از pip برای آپدیت و ارتقای پکیج‌های پایتونی نصب شده نیز استفاده می‌شود. برای این کار می‌توانید نام پکیج یا پکیج‌های مدنظر را به همراه سوییچ upgrade به pip بدهید:

pip install --upgrade requests
pip install --upgrade requests flask numpy

مشاهده کلیه پکیج‌های نصب شده در سیستم یا محیط مجازی شما با استفاده از دستور list امکانپذیر است:

pip list

اما اگر می‌خواهید فقط پکیج‌هایی که نیازمند به‌روزرسانی هستند را ببینید، سوییچ outdated را به کار ببرید:

pip list --outdated

۳) نصب از فایل پیش‌نیازها

برنامه‌نویسان پایتون برای مدیریت پیش‌نیازها و وابستگی‌های پروژه، معمولاً یک فایل به نام requirements.txt می‌سازند که کلیه پکیج‌های موردنیاز اجرای پروژه داخل آن لیست شده است. با استفاده از سوییچ r می‌توانید کلیه پکیج‌های داخل این فایل را توسط pip نصب کنید:

pip install -r requirements.txt

برای ساخت خودکار فایل requirements.txt از محیط فعلی پروژه نیز می‌توانید دستور زیر را وارد کنید:

pip freeze > requirements.txt

۴) نصب با ویژگی‌های اضافی

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

pip install 'SomePackage[PDF]'
pip install 'SomePackage[PDF]==3.0'

به عنوان مثال، برای این که پکیج httpx پایتون از پروتکل HTTP/2 یا پروکسی‌های SOCKS پشتیبانی کند، نیاز است به صورت ویژگی اضافی برای pip تعریف شوند:

pip install httpx[http2]
pip install httpx[socks]

نگاهی عمیق‌تر به ابزار pip

علاوه بر کاربردهای پایه‌ای ابزار pip در پایتون، این ابزار یک سری امکانات پیشرفته‌تر نیز برای کاربران حرفه‌ای در نظر گرفته است که در ادامه به بررسی برخی از مهم‌ترین آنها پرداخت می‌شود.

۱) نصب پکیج از مخازن گیت

با کمک pip می‌توانید پکیج‌های پایتونی مدنظر خود را مستقیماً از مخزن Git نصب کنید. این قابلیت برای زمانی مفید است که پکیج مدنظر شما در مخازن رسمی آپلود نمی‌شود (خصوصی است) یا مثلاً تمایل دارید نسخه‌هایی را نصب کنید که هنوز روی PyPI منتشر نشده‌اند:

pip install git+https://github.com/user/repo.git

اگر می‌خواهید پکیج شما از یک شاخه خاص یا تگ خاص نصب شود، باید برای pip مشخص کنید:

pip install git+https://github.com/user/repo.git@feature-branch
pip install git+https://github.com/user/repo.git@v1.0.0

۲) نصب در حالت قابل ویرایش

زمانی که با دستور pip اقدام به نصب یک پکیج پایتونی می‌کنید، پایتون فایل‌های آن پکیج را درون پوشه‌ای به نام site-packages کپی و ذخیره می‌کند. اما اگر شما توسعه‌دهنده یک پکیج پایتونی هستید، بدون شک نیاز دارید که عملکرد و قابلیت‌های پکیج خود را در لحظه، تست و بررسی کنید. حالت قابل ویرایش یا editable به شما اجازه می‌دهد تغییرات کد را در همان زمان توسعه و کدنویسی، بلافاصله مشاهده و تست کنید:

pip install -e .

در این دستور، پکیج شما به صورت editable از پوشه فعلی توسط pip نصب می‌شود. همچنین می‌توانید به جای نقطه (پوشه فعلی)، مسیر نگهداری فایل‌های پکیج را به پایتون بدهید:

pip install -e /path/to/my_package

۳) نصب از فایل‌های آفلاین

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

pip download SomePackage

با اجرای این دستور، تمام فایل‌های موردنیاز (به‌همراه وابستگی‌ها) در همان پوشه ذخیره می‌شوند. سپس می‌توانید فایل‌های دانلود شده (معمولاً با پسوند whl. یا tar.gz.) را از طریق فلش یا هارد و یا شبکه داخلی به کامپیوتری که آفلاین است منتقل کرده و در آنجا نصب کنید:

pip install ./files/my_package-1.0-py3.whl

استفاده از فایل‌های whl. چون سریعتر (بدون نیاز به build) هستند، توصیه می‌شود.

۴) نصب از آرشیو محلی

چنانچه آرشیوی از پکیج‌های پرکاربرد خود دارید، می‌توانید به راحتی از این آرشیو محلی (local) به عنوان مخزن اصلی pip استفاده کنید:

pip install --no-index --find-links=./packages SomePackage

در این دستور، سوییچ no-index از pip می‌خواهد که به مخزن اصلی PyPI متصل نشود. سوییچ find-links هم مشخص می‌کند pip در چه پوشه‌ای باید دنبال فایل پکیج‌ها بگردد. در این مثال، فرض شده است که فایل‌های آرشیو شما درون پوشه‌ای به اسم packages داخل پوشه جاری قرار داده شده است.

۵) نصب از ایندکس سفارشی

علاوه بر مخازن رسمی پایتون که در PyPI گردآوری شده، شما می‌توانید از سایر مخازن و میرورهای مربوطه نیز استفاده کنید. برای این کار کافیست سوییچ index-url را به pip بدهید:

pip install --index-url http://my.package.repo/simple/ SomePackage

در این دستور، pip به جای مخازن رسمی PyPI، در آدرسی که به آن داده‌اید دنبال پکیج مدنظر گشته و آن را نصب می‌کند.

همانطور که قبلاً در نوشته «استفاده از pip بدون اینترنت» توضیح داده شد، یکی از کاربردهای این سوییچ در مواقعی است که به دلیل فیلترینگ یا قطعی اینترنت بین‌الملل، دسترسی به سرورهای pip مختل شده است. در این حالت می‌توان از مخازن جایگزین pip که داخل کشور میزبانی می‌شوند (مانند مخزن runflare.com)، استفاده کرد.

همچنین می‌توانید مخازن جانبی را به همراه مخازن اصلی استفاده کنید. در این حالت، pip علاوه بر PyPI در مخازنی که مشخص کرده‌اید نیز به دنبال پکیج مدنظر می‌گردد و آن را برای شما نصب می‌کند:

pip install --extra-index-url http://my.package.repo/simple SomePackage

۶) نصب نسخه‌های پیش‌انتشار

به‌طور پیش‌فرض، pip فقط نسخه‌های پایدار پکیج‌ها را نصب می‌کند. برای دسترسی به نسخه‌های آلفا، بتا، RC و … می‌توانید از سوییچ pre استفاده کنید:

pip install --pre SomePackage

مشکلات متداول استفاده از pip

در زیر رایج‌ترین خطاهایی که هنگام کار با pip رخ می‌دهند به همراه علت و راه‌حل آنها آمده است.

۱) خطای عدم شناسایی pip

یکی از رایج‌ترین خطاهای هنگام استفاده از pip، خطای عدم شناسایی آن است.

ERROR: 'pip' is not recognized as an internal or external command

عمدتاً این خطا به دلیل این است که pip در متغیر محیطی PATH سیستم ثبت نشده یا اصلاً pip نصب نیست. ساده‌ترین راه حل این خطا، استفاده از pip به صورت ماژول است:

python -m pip install requests

یا مطمئن شوید که pip نصب است:

python -m ensurepip --upgrade

۲) خطای دسترسی

یکی دیگر از خطاهای متداول pip، خطای عدم دسترسی است که معمولاً به صورت Permission denied یا Access is denied نمایش داده می‌شود. عمدتاً این خطا ناشی از آن است که در حال استفاده از pip در یک پوشه سیستمی هستید که نیاز به دسترسی root یا ادمین دارد. برای حل این مشکل توصیه می‌شود طبق توضیحات بالا، یا نصب را برای یک کاربر خاص انجام دهید یا از محیط مجازی استفاده کنید.

۳) خطای عدم یافتن پکیج

ممکن است حین استفاده از pip با خطای عدم یافتن پکیج مدنظر مواجه شوید.

ERROR: Could not find a version that satisfies the requirement xyz
ERROR: No matching distribution found for xyz

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

۴) خطای تعارض وابستگی‌ها

یکی از مهم‌ترین خطاهای حین استفاده از pip مربوط به زمانی است که دو یا چند پکیج نصب‌شده، نسخه‌های متعارضی از یک وابستگی مشترک نیاز دارند. یعنی پکیج a به نسخه 1 از پکیج x نیاز دارید در حالی که پکیج b به نسخه 2 همان پکیج x نیاز دارد و این دو نسخه از پکیج x با هم سازگاری ندارند. در چنین مواقعی با خطای تعارض وابستگی‌ها (Dependency Conflict) مواجه می‌شوید:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
package-a 1.0 requires package-b>=2.0, but you have package-b 1.5

برای بررسی تعارض‌ها می‌توانید از دستور check استفاده کنید:

pip check

۵) خطای کامپایل

در صورتی که یک یا برخی از پکیج‌های مدنظر شما به کامپایل کد C یا CPP نیاز داشته باشد ولی کامپایلر روی سیستم نصب نباشد، با خطای کامپایل مواجه خواهید شد.

ERROR: Microsoft Visual C++ 14.0 or greater is required.
-- OR --
ERROR: command 'gcc' failed with exit status 1

برای حل این مشکل، یا باید کامپایلر موردنیاز را متناسب با سیستم عامل خود نصب کنید یا از نسخه‌های بیلد شده آن پکیج (فایل whl.) استفاده کنید.

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