اگر تا حالا با تداخل نسخه‌های پکیج‌ها، فایل requirements.txt شلوغ و محیط‌های مجازی گم‌شده در پایتون کلافه شده‌اید، Poetry دقیقاً برای همین ساخته شده است. این ابزار مدرن، مدیریت وابستگی، محیط مجازی، بسته‌بندی و انتشار روی PyPI را در یک فایل pyproject.toml و یک دستور ساده خلاصه می‌کند تا پروژه‌های پایتون و هوش مصنوعی شما قابل تکرار، تمیز و آماده انتشار باشند. در ادامه، نصب، ساخت پروژه، قفل کردن نسخه‌ها و انتشار حرفه‌ای با Poetry را قدم‌به‌قدم یاد می‌گیرید.

Poetry در پایتون چیست و چرا از pip و requirements.txt بهتر است؟

Poetry یک مدیر وابستگی و بسته‌بندی مدرن برای پایتون است که به‌جای requirements.txt پراکنده، همه‌چیز را در pyproject.toml و poetry.lock متمرکز می‌کند، محیط مجازی را خودکار می‌سازد و نصب‌ها را قطعی و تکرارپذیر می‌کند. نتیجه، نصب سریع‌تر تیمی، حل تعارض هوشمند و آماده‌بودن پروژه برای انتشار در PyPI است. در ادامه جزئیات کامل نصب و کار عملی را می‌بینید.

فهرست مطالب

Poetry چیست و چه مشکلی را حل می‌کند؟
پیش‌نیازها و نصب Poetry روی ویندوز، مک و لینوکس
ساخت اولین پروژه با Poetry از صفر
مدیریت وابستگی‌ها؛ افزودن، حذف و قفل کردن نسخه‌ها
محیط مجازی، اجرای اسکریپت و مدیریت دستورات
بسته‌بندی و انتشار پکیج در PyPI با Poetry
Poetry در برابر pip و uv؛ مقایسه معیارمحور
اشتباهات رایج هنگام کار با Poetry
سوالات متداول
جمع‌بندی

Poetry چیست و چه مشکلی را حل می‌کند؟

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

ایده اصلی Poetry، اعلام وابستگی‌ها به‌صورت اعلانی در pyproject.toml و قفل کردن نسخه‌های دقیق و هش‌شده در poetry.lock است. این قفل باعث می‌شود دستور poetry install روی هر ماشین، همان گراف وابستگی یکسان را نصب کند؛ چیزی که pip بدون قفل تضمین نمی‌کند.

تکرارپذیری: نصب قطعی با poetry.lock حتی اگر نسخه جدیدی از یک کتابخانه منتشر شده باشد.
حل تعارض هوشمند: حل‌کننده وابستگی Poetry، محدودیت‌های نسخه را بهتر از pip بررسی می‌کند و زودتر خطای ناسازگاری را گزارش می‌دهد.
همه‌کاره بودن: ساخت پروژه، مدیریت venv، اجرای اسکریپت، بیلد و انتشار — همه با یک ابزار.
استاندارد مدرن: مبتنی بر PEP 517/518 و فایل pyproject.toml که امروز استاندارد اکوسیستم پایتون است.

اگر پروژه‌تان یک اسکریپت ساده تک‌فایلی است، pip کافی است؛ اما برای پروژه‌های تیمی، کتابخانه قابل انتشار یا اپ‌های هوش مصنوعی با وابستگی‌های زیاد، Poetry بهره‌وری و امنیت نصب را چند برابر می‌کند.

پیش‌نیازها و نصب Poetry روی ویندوز، مک و لینوکس

برای شروع فقط به پایتون 3.8 به بالا و دسترسی به ترمینال نیاز دارید. Poetry را به‌صورت ایزوله نصب کنید تا با pip سیستم تداخل نکند؛ نصب رسمی از طریق اسکریپت اختصاصی توصیه می‌شود.

روش پیشنهادی نصب

# نصب رسمی با اسکریپت (لینوکس/مک)
curl -sSL https://install.python-poetry.org | python3 -

# ویندوز (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

# بررسی نصب
poetry --version
poetry self update

روش قدیمی pip install poetry یا pipx install poetry هنوز کار می‌کند اما روش رسمی، Poetry را در محیط ایزوله خودش نصب می‌کند و به‌روزرسانی را با poetry self update ساده می‌کند.

تنظیمات اولیه مهم

# نمایش محل venv هر پروژه برای دیباگ
poetry config --list

# ساخت venv داخل پوشه پروژه (.venv) برای سازگاری با VS Code
poetry config virtualenvs.in-project true --local

# غیرفعال کردن ساخت خودکار venv اگر با conda کار می‌کنید
# poetry config virtualenvs.create false

اگر از قبل با conda یا venv دستی کار می‌کنید، Poetry به‌صورت خودکار محیط فعال را تشخیص می‌دهد؛ در غیر این صورت خودش یک venv جدید می‌سازد. برای دیدن مسیر محیط: poetry env info --path.

ساخت اولین پروژه با Poetry از صفر

دو راه دارید: پروژه صفر بسازید یا پوشه موجود را به Poetry تبدیل کنید. هر دو در کمتر از یک دقیقه انجام می‌شود.

# ساخت پروژه جدید با ساختار استاندارد
poetry new my-ai-tool --name my_ai_tool
cd my-ai-tool

# یا مقداردهی در پوشه موجود (تعاملی)
poetry init

ساختار پیش‌فرض poetry new تمیز و استاندارد است: پوشه پکیج، تست‌ها، README و pyproject.toml آماده.

my-ai-tool/
├── pyproject.toml
├── README.md
├── my_ai_tool/
│   └── __init__.py
└── tests/
    └── __init__.py

آناتومی pyproject.toml

[tool.poetry]
name = "my-ai-tool"
version = "0.1.0"
description = "ابزار پایتون برای پردازش متن با هوش مصنوعی"
authors = ["Your Name <you@example.com>"]
readme = "README.md"
packages = [{include = "my_ai_tool"}]

[tool.poetry.dependencies]
python = "^3.10"
requests = "^2.31.0"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0.0"
ruff = "^0.4.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

نکته کلیدی: نسخه‌ها با ^ یعنی سازگار (caret)؛ Poetry محدوده مجاز را هوشمندانه حل می‌کند و نتیجه را در poetry.lock قفل می‌کند. بعد از هر تغییر، poetry lock را اجرا کنید تا قفل به‌روز شود.

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

مدیریت وابستگی‌ها؛ افزودن، حذف و قفل کردن نسخه‌ها

قدرت اصلی Poetry در همین بخش است: افزودن وابستگی بدون دستکاری دستی فایل‌ها و قفل دقیق نسخه‌ها.

# افزودن وابستگی اصلی
poetry add requests httpx

# افزودن با محدودیت نسخه
poetry add "pydantic>=2.0,<3.0"

# افزودن وابستگی توسعه (dev)
poetry add --group dev pytest ruff mypy

# حذف پکیج
poetry remove httpx

# به‌روزرسانی هوشمند بر اساس محدوده مجاز
poetry update requests

# نصب دقیق از روی قفل (در CI/تیم)
poetry install --no-root

تفاوت poetry install و poetry update: اولی دقیقاً همان نسخه‌های poetry.lock را نصب می‌کند (قطعی)، دومی محدوده‌های pyproject.toml را دوباره حل کرده و lock را بازنویسی می‌کند. در تیم و CI همیشه از install استفاده کنید.

مدیریت نسخه پایتون

# محدود کردن نسخه پایتون پروژه
poetry env use python3.11
# یا
poetry env use /usr/bin/python3.11

# مشاهده وابستگی‌ها به‌صورت درختی
poetry show --tree
poetry show --outdated

برای پروژه‌های هوش مصنوعی که به نسخه خاصی از torch یا numpy وابسته‌اند، قفل Poetry از «کار روی سیستم من» به «کار برای همه» جلوگیری می‌کند.

محیط مجازی، اجرای اسکریپت و مدیریت دستورات

Poetry محیط مجازی را شفاف مدیریت می‌کند؛ نه پوشه‌های گم‌شده، نه فعال‌سازی دستی فراموش‌شده.

# اطلاعات محیط
poetry env info
poetry env list

# اجرای دستور داخل venv بدون فعال‌سازی
poetry run python my_ai_tool/main.py
poetry run pytest -q

# ورود به shell محیط
poetry shell
exit

می‌توانید اسکریپت‌های پرکاربرد را در pyproject.toml تعریف کنید تا تیم با یک دستور اجرا کند:

[tool.poetry.scripts]
my-tool = "my_ai_tool.cli:main"

[tool.poetry.group.dev.dependencies]
# اجرای تسک سفارشی با poe یا taskipy هم ممکن است

با این تعریف، بعد از poetry install دستور my-tool مستقیم در venv در دسترس است. برای اجرای نوت‌بوک یا اسکریپت‌های تحلیل داده، poetry run jupyter lab یا poetry run python -m my_ai_tool.app را به کار ببرید.

بسته‌بندی و انتشار پکیج در PyPI با Poetry

یکی از دلایلی که Poetry محبوب شد، بیلد و انتشار بدون دردسر است؛ دیگر نیازی به setup.py دستی و twine جداگانه ندارید.

# بیلد سورس و ویل
poetry build

# بررسی محتوای بیلد
ls dist/
# my_ai_tool-0.1.0-py3-none-any.whl
# my_ai_tool-0.1.0.tar.gz

# انتشار در PyPI (نیاز به توکن)
poetry config pypi-token.pypi pypi-xxxxxxxx
poetry publish

# انتشار آزمایشی در TestPyPI
poetry publish -r testpypi

# افزایش نسخه طبق semver
poetry version patch  # 0.1.0 -> 0.1.1
poetry version minor  # 0.1.1 -> 0.2.0
poetry version major  # 0.2.0 -> 1.0.0

برای انتشار ایمن، از توکن PyPI با اسکوپ محدود پروژه استفاده کنید و آن را در متغیر محیطی POETRY_PYPI_TOKEN_PYPI نگه دارید، نه در کد. اگر می‌خواهید جریان کلاسیک انتشار با setup.py و twine را هم مقایسه کنید، این راهنما مکمل خوبی است: آموزش ساخت و انتشار پکیج پایتون در PyPI از صفر تا نصب.

نکته امنیتی: قبل از publish، poetry check و poetry build را اجرا کنید و فایل dist را بررسی کنید تا فایل‌های اضافی مثل .env بسته‌بندی نشود. برای جلوگیری، از exclude در pyproject.toml استفاده کنید.

[tool.poetry]
exclude = ["tests", ".env", "notebooks"]

Poetry در برابر pip و uv؛ مقایسه معیارمحور

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

معیار	Poetry	pip + venv	uv
مدیریت وابستگی	اعلانی + حل‌کننده قوی + lock قطعی	دستی requirements.txt، بدون lock پیش‌فرض	بسیار سریع، سازگار با pip، lock دارد
محیط مجازی	خودکار، ایزوله، قابل تنظیم	دستی با python -m venv	مدیریت خودکار، سریع
بسته‌بندی و انتشار	یکپارچه (build + publish)	نیاز به build + twine جداگانه	پشتیبانی محدودتر، تمرکز بر نصب
سرعت نصب	متوسط (حل وابستگی دقیق)	کند تا متوسط	بسیار سریع (Rust)
مناسب برای	کتابخانه، پروژه تیمی، انتشار PyPI	اسکریپت ساده، آموزش مقدماتی	پروژه‌های بزرگ با نصب سنگین
منحنی یادگیری	کم تا متوسط	کم	کم

اگر سرعت خام نصب اولویت مطلق است، uv می‌درخشد؛ اگر انتشار تمیز و مدیریت وابستگی قابل اعتماد می‌خواهید، Poetry انتخاب متعادل‌تری است. بسیاری از تیم‌ها حتی Poetry برای مدیریت وابستگی و uv برای نصب سریع در CI را ترکیب می‌کنند.

اشتباهات رایج هنگام کار با Poetry

این خطاها را زودتر بشناسید تا ساعت‌ها دیباگ ذخیره کنید.

کامیت نکردن poetry.lock: قفل را حتماً کامیت کنید؛ در غیر این صورت نصب تیمی غیرقطعی می‌شود. فقط برای کتابخانه‌هایی که به‌عنوان وابستگیِ دیگران نصب می‌شوند، بحث متفاوت است.
نصب با pip داخل پروژه Poetry: ترکیب pip و Poetry گراف وابستگی را به هم می‌ریزد. همیشه از poetry add استفاده کنید و اگر مجبور به pip شدید، بلافاصله poetry lock را بازسازی کنید.
نسخه پایتون شناور: نوشتن python = "*" باعث نصب روی نسخه‌های ناسازگار می‌شود. محدوده دقیق مثل ^3.10 بگذارید.
فراموشی poetry install در CI: در CI از poetry install --no-root --no-interaction استفاده کنید، نه update که قفل را تغییر می‌دهد.
بسته‌بندی فایل‌های محرمانه: بدون exclude، فایل‌های .env یا کلیدها ممکن است وارد dist شوند. قبل از publish، محتوای dist را باز کنید.

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

آیا Poetry جایگزین کامل pip است؟

برای پروژه‌های Poetry بله؛ تمام نصب‌ها را با Poetry انجام دهید. اما pip همچنان برای نصب تک‌ابزارهای سیستمی مثل pipx یا موارد خارج از پروژه کاربرد دارد. در پروژه Poetry از pip استفاده نکنید تا قفل به هم نریزد.

تفاوت poetry.lock و pyproject.toml چیست؟

pyproject.toml محدوده‌های مجاز نسخه را اعلان می‌کند، poetry.lock نسخه دقیق حل‌شده با هش را قفل می‌کند. اولی را ویرایش می‌کنید، دومی را کامیت می‌کنید تا نصب همه یکسان باشد.

چطور Poetry را برای پروژه موجود با requirements.txt مهاجرت دهم؟

داخل پوشه پروژه poetry init بزنید، وابستگی‌ها را با poetry add یکی‌یکی اضافه کنید یا از ابزار poetry import و اسکریپت‌های تبدیل استفاده کنید. سپس poetry install و تست کامل بگیرید و قفل را کامیت کنید.

Poetry با Docker و CI/CD سازگار است؟

بله. در Dockerfile، Poetry را نصب کنید، فایل‌های pyproject.toml و poetry.lock را کپی کنید، سپس poetry install --no-root --no-dev بزنید. در GitHub Actions از اکشن رسمی setup-python + کش Poetry استفاده کنید تا نصب سریع و قطعی باشد.

آیا Poetry برای پروژه‌های هوش مصنوعی با وابستگی‌های سنگین مناسب است؟

بله، به‌ویژه برای تکرارپذیری. برای وابستگی‌های خیلی سنگین مثل CUDA، ترکیب Poetry با uv برای سرعت نصب یا استفاده از گروه‌های وابستگی اختیاری توصیه می‌شود. گروه dev را از نصب پروداکشن جدا نگه دارید.

چگونه نسخه پکیج را به‌صورت خودکار افزایش دهم؟

از poetry version patch/minor/major استفاده کنید که pyproject.toml را به‌روز می‌کند، سپس تگ گیت بزنید و poetry publish کنید. این کار از خطای دستی نسخه جلوگیری می‌کند.

جمع‌بندی

Poetry پایتون را از مدیریت دستی وابستگی نجات می‌دهد و سه کار را یکجا انجام می‌دهد: اعلان تمیز در pyproject.toml، قفل قطعی در poetry.lock و انتشار ساده روی PyPI. اگر امروز شروع می‌کنید، این چک‌لیست را دنبال کنید:

Poetry را با اسکریپت رسمی نصب و virtualenvs.in-project true را فعال کنید.
پروژه را با poetry new یا poetry init بسازید و نسخه پایتون را دقیق محدود کنید.
وابستگی‌ها را فقط با poetry add مدیریت و قفل را کامیت کنید.
اجرا را با poetry run و انتشار را با poetry build && poetry publish انجام دهید.
قبل از انتشار، poetry check و بازبینی dist را فراموش نکنید.

با همین جریان، پروژه بعدی پایتون یا هوش مصنوعی شما از روز اول تمیز، قابل نصب برای هم‌تیمی‌ها و آماده انتشار خواهد بود — بدون جنگ با requirements.txt.

آموزش Poetry در پایتون؛ مدیریت وابستگی و انتشار پکیج