BUNDLE-INSTALL(1) General Commands Manual BUNDLE-INSTALL(1)

bundle-install - وابستگی‌های مشخص‌شده در Gemfile را نصب می‌کند

bundle install [--force] [--full-index] [--gemfile=GEMFILE] [--jobs=NUMBER] [--local] [--lockfile=LOCKFILE] [--no-cache] [--no-lock] [--prefer-local] [--quiet] [--retry=NUMBER] [--standalone[=GROUP[ GROUP...]]] [--trust-policy=TRUST-POLICY] [--target-rbconfig=TARGET-RBCONFIG]

بسته‌های gem مشخص‌شده در Gemfile(5) شما را نصب می‌کند. اگر این نخستین باری است که bundle install را اجرا می‌کنید (و فایل Gemfile.lock وجود ندارد)، Bundler تمام منابع دوردست (remote) را واکشی کرده، وابستگی‌ها را حل‌وفصل می‌کند و تمامی gemهای مورد نیاز را نصب می‌نماید.

اگر فایل Gemfile.lock وجود داشته باشد و شما Gemfile(5) خود را به‌روزرسانی نکرده باشید، Bundler تمام منابع دوردست را واکشی می‌کند، اما به جای حل‌وفصل وابستگی‌ها، از وابستگی‌های مشخص‌شده در Gemfile.lock استفاده خواهد کرد.

اگر فایل Gemfile.lock وجود داشته باشد و شما Gemfile(5) خود را به‌روزرسانی کرده باشید، Bundler از وابستگی‌های موجود در Gemfile.lock برای تمامی gemهایی که به‌روزرسانی نکرده‌اید استفاده می‌کند، اما وابستگی‌های gemهایی را که به‌روزرسانی کرده‌اید دوباره حل‌وفصل خواهد کرد. اطلاعات بیشتر درباره این فرآیند به‌روزرسانی را می‌توانید در بخش به‌روزرسانی محافظه‌کارانه (CONSERVATIVE UPDATING) در ادامه بیابید.

نصب مجدد اجباری تمام gemها، حتی اگر از قبل نصب شده باشند.
به جای فراخوانی نقطه پایانی API مربوط به Rubygems (پیش‌فرض)، یک فایل نمایه (index) از تمام gemها را که در حال حاضر حجیم است دانلود و کش می‌کند. با فعال‌سازی این گزینه می‌توان عملکرد را برای بسته‌های بزرگی که به ندرت تغییر می‌کنند بهبود بخشید.
مکان Gemfile(5) که Bundler باید از آن استفاده کند. مقدار پیش‌فرض آن فایل Gemfile(5) در دایرکتوری کاری جاری است. به‌طور کلی، Bundler فرض می‌کند که مکان Gemfile(5) همان ریشه پروژه است و تلاش می‌کند Gemfile.lock و vendor/cache را نسبت به این مکان پیدا کند.
حداکثر تعداد کارهای موازی برای دانلود و نصب. مقدار پیش‌فرض برابر با تعداد پردازنده‌های در دسترس است.
برای اتصال به rubygems.org تلاشی نمی‌کند. در عوض، Bundler از gemهایی استفاده می‌کند که از قبل در کش Rubygems یا در vendor/cache موجود هستند. توجه داشته باشید که اگر gem خاصی مناسب برای پلتفرم در rubygems.org وجود داشته باشد، پیدا نخواهد شد.
مکان فایل lockfile که Bundler باید استفاده کند. مقدار پیش‌فرض آن همان مکان Gemfile است که .lock به انتهای آن ضمیمه شده است.
استفاده اجباری از gemهای نصب‌شده به‌صورت محلی، یا gemهایی که از قبل در کش Rubygems یا در vendor/cache موجود هستند در هنگام حل‌وفصل، حتی اگر نسخه‌های جدیدتری از راه دور در دسترس باشند. تنها برای gemهایی که به‌صورت محلی موجود نیستند اقدام به اتصال به rubygems.org می‌کند.
کش موجود در vendor/cache را با gemهای تازه بسته‌بندی‌شده به‌روزرسانی نمی‌کند. این کار هیچ‌یک از gemهای موجود در کش را حذف نمی‌کند، اما از کش شدن gemهای تازه بسته‌بندی‌شده در حین نصب جلوگیری می‌کند.
فایل lockfile ایجاد نمی‌کند. زمانی کاربرد دارد که می‌خواهید وابستگی‌ها را نصب کنید اما نسخه‌های gemها قفل نشوند. برای توسعه کتابخانه‌ها و شرایط دیگری که انتظار می‌رود کد با طیفی از نسخه‌های وابستگی کار کند، توصیه می‌شود.
این گزینه همان اثری را دارد که استفاده از lockfile false در Gemfile ایجاد می‌کند. برای اطلاعات بیشتر به gemfile(5) مراجعه کنید.
اطلاعات پیشرفت را در خروجی استاندارد چاپ نمی‌کند.
درخواست‌های ناموفق شبکه یا git را به تعداد number بار تکرار می‌کند.
بسته‌ای ایجاد می‌کند که می‌تواند در زمان اجرا بدون وابستگی به Rubygems یا Bundler کار کند. می‌توان فهرستی از گروه‌ها را که با فاصله جدا شده‌اند برای نصب مشخص کرد. Bundler دایرکتوری با نام bundle ایجاد کرده و بسته را در آنجا نصب می‌کند. همچنین یک فایل bundle/bundler/setup.rb ایجاد می‌کند تا طبق نیاز جایگزین راه‌اندازی پیش‌فرض Bundler شود.
سیاست امنیتی Rubygems با نام policy را اعمال می‌کند، که در آن policy یکی از مقادیر HighSecurity، MediumSecurity، LowSecurity، AlmostNoSecurity، یا NoSecurity است. برای جزئیات بیشتر، لطفاً به مستندات امضای Rubygems که پیوند آن در بخش همچنین ببینید (SEE ALSO) آمده است مراجعه کنید.
مسیر rbconfig.rb برای پلتفرم هدف استقرار.

پیش‌فرض‌های Bundler برای محیط توسعه بهینه‌سازی شده‌اند. برای تغییر به پیش‌فرض‌های بهینه‌سازی‌شده برای استقرار و CI، از تنظیمات deployment استفاده کنید. حالت استقرار را روی رایانه‌های توسعه فعال نکنید، زیرا هنگام تغییر Gemfile(5) باعث ایجاد خطا می‌شود.

1.
وجود Gemfile.lock الزامی است.
برای اطمینان از اینکه همان نسخه‌هایی از gemها که هنگام توسعه و آزمایش استفاده کرده‌اید در استقرار نیز به کار می‌روند، وجود Gemfile.lock الزامی است.
این موضوع عمدتاً برای اطمینان از این است که سپردن (commit) فایل Gemfile.lock خود را به سیستم کنترل نسخه فراموش نکنید.
2.
فایل Gemfile.lock باید به‌روز باشد
در محیط توسعه، می‌توانید Gemfile(5) خود را تغییر داده و دوباره bundle install را اجرا کنید تا وضعیت لحظه‌ای (snapshot) فایل Gemfile.lock خود را به‌طور محافظه‌کارانه به‌روزرسانی کنید.
در محیط استقرار، فایل Gemfile.lock شما باید با تغییرات اعمال‌شده در Gemfile(5) کاملاً به‌روز باشد.
3.
بسته‌های gem در vendor/bundle نصب می‌شوند، نه در مکان پیش‌فرض سیستم شما
در محیط توسعه، به اشتراک گذاشتن gemهای مورد استفاده در برنامه‌تان با سایر برنامه‌ها و اسکریپت‌هایی که روی سیستم اجرا می‌شوند راحت‌تر است.
در محیط استقرار، ایزوله‌سازی یک پیش‌فرض مهم‌تر است. علاوه بر این، کاربری که برنامه را مستقر می‌کند ممکن است مجوز نصب gemها را روی سیستم نداشته باشد، یا وب‌سرور ممکن است اجازه خواندن آن‌ها را نداشته باشد.
در نتیجه، هنگامی که deployment پیکربندی شده باشد، دستور bundle install بسته‌های gem را در دایرکتوری vendor/bundle درون برنامه نصب می‌کند. این رفتار را می‌توان با استفاده از تنظیمات path بازنویسی کرد.

به‌طور پیش‌فرض، bundle install تمام gemهای موجود در تمام گروه‌های Gemfile(5) شما را نصب می‌کند، به جز مواردی که برای پلتفرم دیگری اعلان شده‌اند.

با این حال، می‌توانید صراحتاً با استفاده از تنظیمات without به Bundler بگویید که از نصب گروه‌های خاصی صرف‌نظر کند. این تنظیم فهرستی از گروه‌ها را که با فاصله جدا شده‌اند دریافت می‌کند.

با اینکه تنظیم without از نصب gemها در گروه‌های مشخص‌شده صرف‌نظر می‌کند، bundle install همچنان آن gemها را دانلود کرده و از آن‌ها برای حل‌وفصل وابستگی‌های هر gem در Gemfile(5) شما استفاده می‌کند.

این رفتار برای آن است که نصب مجموعه‌ای متفاوت از گروه‌ها روی سیستمی دیگر (مانند یک سرور پروداکشن) باعث تغییر gemها و نسخه‌هایی نشود که قبلاً بر اساس آن‌ها توسعه و آزمایش را انجام داده‌اید.

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

برای یک نمونه ساده، Gemfile(5) زیر را در نظر بگیرید:

source 'https://rubygems.org'
gem 'sinatra'
group :production do
  gem 'rack-perftools-profiler'
end

در این حالت، sinatra به هر نسخه‌ای از Rack وابسته است (>= 1.0)، در حالی که rack-perftools-profiler به نسخه 1.x وابسته است (~> 1.0).

وقتی دستور bundle config without production را در محیط توسعه پیکربندی می‌کنید، وابستگی‌های rack-perftools-profiler نیز بررسی می‌شوند. به این ترتیب، تمام وقت خود را صرف توسعه بر پایه Rack 2.0 و استفاده از APIهای جدید ناموجود در Rack 1.x نمی‌کنید، تا در نهایت وقتی از گروه production استفاده می‌شود، Bundler ناگهان به Rack 1.2 بازگردد.

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

این همچنین بدان معناست که نمی‌توانید نسخه‌های متفاوتی از یک gem یکسان را در گروه‌های مختلف قرار دهید، زیرا انجام این کار منجر به استفاده از مجموعه‌های متفاوتی از وابستگی‌ها در محیط‌های توسعه و پروداکشن خواهد شد. به دلیل پیچیدگی‌های فرآیند حل‌وفصل وابستگی، این امر معمولاً فراتر از gemهای فهرست‌شده در Gemfile(5) تأثیر می‌گذارد و می‌تواند به شکلی چشمگیر gemهایی را که استفاده می‌کنید دگرگون کند.

هنگامی که bundle install را اجرا می‌کنید، Bundler نام‌های کامل و نسخه‌های تمام gemهایی را که استفاده کرده‌اید (از جمله وابستگی‌های gemهای مشخص‌شده در Gemfile(5)) در فایلی به نام Gemfile.lock ذخیره و ماندگار می‌کند.

دستور Bundler در تمام فراخوانی‌های بعدی bundle install از این فایل استفاده می‌کند، که تضمین می‌نماید شما همیشه دقیقاً از همان کد استفاده می‌کنید، حتی زمانی که برنامه‌تان بین رایانه‌های مختلف جابه‌جا شود.

به دلیل شیوه کارکرد حل‌وفصل وابستگی‌ها، حتی یک تغییر به ظاهر کوچک (برای مثال، به‌روزرسانی به یک انتشار فرعی از وابستگی یکی از gemها در Gemfile(5)) می‌تواند به نیاز به gemهایی کاملاً متفاوت برای برآورده کردن تمام وابستگی‌ها منجر شود.

در نتیجه، شما باید فایل Gemfile.lock خود را، چه در برنامه‌ها و چه در gemها، به سیستم کنترل نسخه اضافه کنید. اگر این کار را نکنید، هر سیستمی که مخزن شما را دریافت کند (از جمله سرور پروداکشن شما) دوباره تمام وابستگی‌ها را حل‌وفصل خواهد کرد، که در صورت به‌روزرسانی هر یک از gemها در Gemfile(5) یا هر کدام از وابستگی‌های آن‌ها، منجر به استفاده از نسخه‌های متفاوتی از کد شخص‌ثالث خواهد شد.

هنگامی که Bundler برای اولین بار عرضه شد، فایل Gemfile.lock درون فایل .gitignore پیش‌فرض به همراه gemهای تولیدشده قرار داشت. اما با گذشت زمان، مشخص شد که این رویه دردسرهای ناشی از وابستگی‌های خراب را به مشارکت‌کنندگان جدید تحمیل می‌کند، در حالی که مشارکت‌کنندگان فعلی را احتمالاً از مشکل بی‌خبر می‌گذارد. از آنجا که bundle install معمولاً نخستین گام برای مشارکت در پروژه است، دردسر وابستگی‌های ناقص مشارکت‌کنندگان جدید را دلسرد می‌کرد. در نتیجه، ما راهنمای خود را برای توسعه‌دهندگان gem بازبینی کرده‌ایم و اکنون ثبت کردن فایل قفل را برای gemها نیز توصیه می‌کنیم.

هنگامی که تغییری در Gemfile(5) ایجاد می‌کنید و سپس bundle install را اجرا می‌نمایید، Bundler تنها gemهایی را که تغییر داده‌اید به‌روزرسانی خواهد کرد.

به عبارت دیگر، اگر gemی که شما آن را تغییر نداده‌اید پیش از اجرای bundle install کار می‌کرده است، همچنان به استفاده از دقیقاً همان نسخه‌های تمامی وابستگی‌هایی که پیش از به‌روزرسانی استفاده می‌کرد ادامه خواهد داد.

بیایید به یک مثال نگاه کنیم. این Gemfile(5) اولیه شماست:

source 'https://rubygems.org'
gem 'actionpack', '2.3.8'
gem 'activemerchant'

در این حالت، هر دو بسته actionpack و activemerchant به activesupport وابسته هستند. بسته actionpack به activesupport 2.3.8 و rack ~> 1.1.0 وابسته است، در حالی که بسته activemerchant به activesupport >= 2.3.2، braintree >= 2.0.0، و builder >= 2.0.0 وابستگی دارد.

هنگامی که وابستگی‌ها برای نخستین بار حل‌وفصل می‌شوند، Bundler نسخه activesupport 2.3.8 را انتخاب می‌کند، که نیازهای هر دو gem موجود در Gemfile(5) شما را برآورده می‌سازد.

سپس، شما Gemfile(5) خود را بدین صورت تغییر می‌دهید:

source 'https://rubygems.org'
gem 'actionpack', '3.0.0.rc'
gem 'activemerchant'

بسته actionpack 3.0.0.rc شامل تعدادی وابستگی جدید است، و وابستگی activesupport را به = 3.0.0.rc و وابستگی rack را به ~> 1.2.1 به‌روزرسانی می‌کند.

وقتی bundle install را اجرا می‌کنید، Bundler متوجه می‌شود که شما بسته actionpack را تغییر داده‌اید، اما بسته activemerchant دست‌نخورده باقی مانده است. بنابراین بسته‌هایی را که در حال حاضر برای برآورده کردن نیازمندی‌های آن استفاده می‌شوند ارزیابی می‌کند:

همچنین برای برآورده کردن یک وابستگی در activemerchant استفاده شده است، که در حال حاضر به‌روزرسانی نمی‌شود
در حال حاضر برای برآورده کردن وابستگی دیگری استفاده نمی‌شود

از آنجا که شما صراحتاً به‌روزرسانی activemerchant را درخواست نکرده‌اید، انتظار ندارید که پس از به‌روزرسانی actionpack ناگهان از کار بیفتد. با این حال، برآورده کردن وابستگی جدید activesupport 3.0.0.rc در actionpack نیازمند به‌روزرسانی یکی از وابستگی‌های آن است.

اگرچه activemerchant وابستگی بسیار منعطفی را تعریف کرده که از نظر تئوری با activesupport 3.0.0.rc همخوانی دارد، اما Bundler با بسته‌هایی در Gemfile(5) که تغییر نکرده‌اند همراه با وابستگی‌هایشان به عنوان یک واحد یکپارچه (اتمیک) برخورد می‌کند. در این مورد، وابستگی activemerchant به صورت activemerchant 1.7.1 + activesupport 2.3.8 در نظر گرفته می‌شود، بنابراین bundle install گزارش می‌دهد که نمی‌تواند actionpack را به‌روزرسانی کند.

برای به‌روزرسانی صریح actionpack، از جمله وابستگی‌های آن که سایر gemهای موجود در Gemfile(5) همچنان به آن‌ها وابسته‌اند، دستور bundle update actionpack را اجرا کنید (به bundle update(1) مراجعه نمایید).

خلاصه: به‌طور کلی، پس از ایجاد تغییر در Gemfile(5)، ابتدا باید اجرای bundle install را امتحان کنید، که تضمین می‌کند هیچ gem دیگری در Gemfile(5) تحت تأثیر این تغییر قرار نخواهد گرفت. اگر این کار نتیجه نداد، دستور bundle update(1) bundle-update.1.html را اجرا کنید.

September 2025