{
    "mode": "man",
    "parameter": "Gemfile",
    "section": "5",
    "url": "https://www.chedong.com/phpMan.php/man/Gemfile/5/json",
    "generated": "2026-05-30T06:06:36Z",
    "synopsis": "A Gemfile describes the gem dependencies required to execute associated Ruby code.\nPlace  the Gemfile in the root of the directory containing the associated code. For instance,\nin a Rails application, place the Gemfile in the same directory as the Rakefile.",
    "sections": {
        "NAME": {
            "content": "Gemfile - A format for describing gem dependencies for Ruby programs\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "A Gemfile describes the gem dependencies required to execute associated Ruby code.\n\nPlace  the Gemfile in the root of the directory containing the associated code. For instance,\nin a Rails application, place the Gemfile in the same directory as the Rakefile.\n",
            "subsections": []
        },
        "SYNTAX": {
            "content": "A Gemfile is evaluated as Ruby code, in a context which makes available a number  of  methods\nused to describe the gem requirements.\n",
            "subsections": []
        },
        "GLOBAL SOURCES": {
            "content": "At  the  top of the Gemfile, add a line for the Rubygems source that contains the gems listed\nin the Gemfile.\n\n\n\nsource \"https://rubygems.org\"\n\n\n\nIt is possible, but not recommended as of Bundler 1.7, to add multiple global  source  lines.\nEach of these sources MUST be a valid Rubygems repository.\n\nSources  are checked for gems following the heuristics described in SOURCE PRIORITY. If a gem\nis found in more than one global source, Bundler will print a warning  after  installing  the\ngem  indicating  which source was used, and listing the other sources where the gem is avail‐\nable. A specific source can be selected for gems that need to use a non-standard  repository,\nsuppressing this warning, by using the :source option or a source block.\n\nCREDENTIALS\nSome  gem  sources require a username and password. Use bundle config(1) bundle-config.1.html\nto set the username and password for any of the sources that need it. The command must be run\nonce  on each computer that will install the Gemfile, but this keeps the credentials from be‐\ning stored in plain text in version control.\n\n\n\nbundle config gems.example.com user:password\n\n\n\nFor some sources, like a company Gemfury account, it may be easier to include the credentials\nin the Gemfile as part of the source URL.\n\n\n\nsource \"https://user:password@gems.example.com\"\n\n\n\nCredentials in the source URL will take precedence over credentials set using config.\n",
            "subsections": []
        },
        "RUBY": {
            "content": "If your application requires a specific Ruby version or engine, specify your requirements us‐\ning the ruby method, with the following arguments. All parameters are OPTIONAL unless  other‐\nwise specified.\n",
            "subsections": [
                {
                    "name": "VERSION (required)",
                    "content": "The version of Ruby that your application requires. If your application requires an alternate\nRuby engine, such as JRuby, Rubinius or TruffleRuby, this should be the Ruby version that the\nengine is compatible with.\n\n\n\nruby \"1.9.3\"\n\n\n\nENGINE\nEach application may specify a Ruby engine. If an engine is specified, an engine version must\nalso be specified.\n\nWhat exactly is an Engine? - A Ruby engine is an implementation of the Ruby language.\n\n•   For background: the reference or original implementation of the Ruby programming language\nis  called  Matz´s  Ruby  Interpreter  https://en.wikipedia.org/wiki/RubyMRI, or MRI for\nshort. This is named after Ruby creator Yukihiro Matsumoto, also known as  Matz.  MRI  is\nalso known as CRuby, because it is written in C. MRI is the most widely used Ruby engine.\n\n•   Other implementations https://www.ruby-lang.org/en/about/ of Ruby exist. Some of the more\nwell-known   implementations   include   Rubinius   https://rubinius.com/,   and    JRuby\nhttp://jruby.org/.  Rubinius  is  an  alternative implementation of Ruby written in Ruby.\nJRuby is an implementation of Ruby on the JVM, short for Java Virtual Machine.\n\n\n\nENGINE VERSION\nEach application may specify a Ruby engine version. If an engine version is specified, an en‐\ngine  must also be specified. If the engine is \"ruby\" the engine version specified must match\nthe Ruby version.\n\n\n\nruby \"1.8.7\", :engine => \"jruby\", :engineversion => \"1.6.7\"\n\n\n\nPATCHLEVEL\nEach application may specify a Ruby patchlevel.\n\n\n\nruby \"2.0.0\", :patchlevel => \"247\"\n\n\n"
                }
            ]
        },
        "GEMS": {
            "content": "Specify gem requirements using the gem method, with the following arguments.  All  parameters\nare OPTIONAL unless otherwise specified.\n",
            "subsections": [
                {
                    "name": "NAME (required)",
                    "content": "For each gem requirement, list a single gem line.\n\n\n\ngem \"nokogiri\"\n\n\n\nVERSION\nEach gem MAY have one or more version specifiers.\n\n\n\ngem \"nokogiri\", \">= 1.4.2\"\ngem \"RedCloth\", \">= 4.1.0\", \"< 4.2.0\"\n\n\n\nREQUIRE AS\nEach  gem  MAY  specify files that should be used when autorequiring via Bundler.require. You\nmay pass an array with multiple files or true if the file you want required has the same name\nas gem or false to prevent any file from being autorequired.\n\n\n\ngem \"redis\", :require => [\"redis/connection/hiredis\", \"redis\"]\ngem \"webmock\", :require => false\ngem \"byebug\", :require => true\n\n\n\nThe argument defaults to the name of the gem. For example, these are identical:\n\n\n\ngem \"nokogiri\"\ngem \"nokogiri\", :require => \"nokogiri\"\ngem \"nokogiri\", :require => true\n\n\n\nGROUPS\nEach  gem MAY specify membership in one or more groups. Any gem that does not specify member‐\nship in any group is placed in the default group.\n\n\n\ngem \"rspec\", :group => :test\ngem \"wirble\", :groups => [:development, :test]\n\n\n\nThe Bundler runtime allows its two main methods, Bundler.setup and Bundler.require, to  limit\ntheir impact to particular groups.\n\n\n\n# setup adds gems to Ruby´s load path\nBundler.setup                    # defaults to all groups\nrequire \"bundler/setup\"          # same as Bundler.setup\nBundler.setup(:default)          # only set up the default group\nBundler.setup(:test)             # only set up the test group (but `not` default)\nBundler.setup(:default, :test)   # set up the default and test groups, but no others\n\n# require requires all of the gems in the specified groups\nBundler.require                  # defaults to the default group\nBundler.require(:default)        # identical\nBundler.require(:default, :test) # requires the default and test groups\nBundler.require(:test)           # requires the test group\n\n\n\nThe  Bundler  CLI allows you to specify a list of groups whose gems bundle install should not\ninstall with the without configuration.\n\nTo specify multiple groups to ignore, specify a list of groups separated by spaces.\n\n\n\nbundle config set --local without test\nbundle config set --local without development test\n\n\n\nAlso, calling Bundler.setup with no parameters, or calling require \"bundler/setup\" will setup\nall groups except for the ones you excluded via --without (since they are not available).\n\nNote  that  on bundle install, bundler downloads and evaluates all gems, in order to create a\nsingle canonical list of all of the required gems and their dependencies. This means that you\ncannot  list  different  versions of the same gems in different groups. For more details, see\nUnderstanding Bundler https://bundler.io/rationale.html.\n\nPLATFORMS\nIf a gem should only be used in a particular platform or set of platforms,  you  can  specify\nthem.  Platforms  are essentially identical to groups, except that you do not need to use the\n--without install-time flag to exclude groups of gems for other platforms.\n\nThere are a number of Gemfile platforms:\n\nruby   C Ruby (MRI), Rubinius or TruffleRuby, but NOT Windows\n\nmri    Same as ruby, but only C Ruby (MRI)\n\nmingw  Windows 32 bit ´mingw32´ platform (aka RubyInstaller)\n\nx64mingw\nWindows 64 bit ´mingw32´ platform (aka RubyInstaller x64)\n\nrbx    Rubinius\n\njruby  JRuby\n"
                },
                {
                    "name": "truffleruby",
                    "content": "TruffleRuby\n\nmswin  Windows\n\nYou can restrict further by platform and version for all platforms  except  for  rbx,  jruby,\ntruffleruby and mswin.\n\nTo  specify a version in addition to a platform, append the version number without the delim‐\niter to the platform. For example, to specify that a gem should only  be  used  on  platforms\nwith Ruby 2.3, use:\n\n\n\nruby23\n\n\n\nThe full list of platforms and supported versions includes:\n\nruby   1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6\n\nmri    1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6\n\nmingw  1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6\n\nx64mingw\n2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6\n\nAs with groups, you can specify one or more platforms:\n\n\n\ngem \"weakling\",   :platforms => :jruby\ngem \"ruby-debug\", :platforms => :mri18\ngem \"nokogiri\",   :platforms => [:mri18, :jruby]\n\n\n\nAll   operations  involving  groups  (bundle  install  bundle-install.1.html,  Bundler.setup,\nBundler.require) behave exactly the same as if any groups not matching the  current  platform\nwere explicitly excluded.\n\nSOURCE\nYou can select an alternate Rubygems repository for a gem using the ´:source´ option.\n\n\n\ngem \"someinternalgem\", :source => \"https://gems.example.com\"\n\n\n\nThis  forces the gem to be loaded from this source and ignores any global sources declared at\nthe top level of the file. If the gem does not exist in this  source,  it  will  not  be  in‐\nstalled.\n\nBundler  will  search  for  child dependencies of this gem by first looking in the source se‐\nlected for the parent, but if they are not found there, it will fall back on  global  sources\nusing the ordering described in SOURCE PRIORITY.\n\nSelecting a specific source repository this way also suppresses the ambiguous gem warning de‐\nscribed above in GLOBAL SOURCES (#source).\n\nUsing the :source option for an individual gem will also make that source available as a pos‐\nsible  global  source  for  any  other gems which do not specify explicit sources. Thus, when\nadding gems with explicit sources, it is recommended that you also ensure all other  gems  in\nthe Gemfile are using explicit sources.\n\nGIT\nIf  necessary, you can specify that a gem is located at a particular git repository using the\n:git parameter. The repository can be accessed via several protocols:\n"
                },
                {
                    "name": "HTTP(S)",
                    "content": "gem \"rails\", :git => \"https://github.com/rails/rails.git\"\n\nSSH    gem \"rails\", :git => \"git@github.com:rails/rails.git\"\n\ngit    gem \"rails\", :git => \"git://github.com/rails/rails.git\"\n\nIf using SSH, the user that you use to run bundle install  MUST  have  the  appropriate  keys\navailable in their $HOME/.ssh.\n\nNOTE: http:// and git:// URLs should be avoided if at all possible. These protocols are unau‐\nthenticated, so a man-in-the-middle attacker can deliver malicious code and  compromise  your\nsystem. HTTPS and SSH are strongly preferred.\n\nThe  group,  platforms, and require options are available and behave exactly the same as they\nwould for a normal gem.\n\nA git repository SHOULD have at least one file, at the root of the directory  containing  the\ngem,  with  the  extension .gemspec. This file MUST contain a valid gem specification, as ex‐\npected by the gem build command.\n\nIf a git repository does not have a .gemspec, bundler will attempt to create one, but it will\nnot  contain any dependencies, executables, or C extension compilation instructions. As a re‐\nsult, it may fail to properly integrate into your application.\n\nIf a git repository does have a .gemspec for the gem you attached it to, a version specifier,\nif  provided, means that the git repository is only valid if the .gemspec specifies a version\nmatching the version specifier. If not, bundler will print a warning.\n\n\n\ngem \"rails\", \"2.3.8\", :git => \"https://github.com/rails/rails.git\"\n# bundle install will fail, because the .gemspec in the rails\n# repository´s master branch specifies version 3.0.0\n\n\n\nIf a git repository does not have a .gemspec for the gem you attached it to, a version speci‐\nfier MUST be provided. Bundler will use this version in the simple .gemspec it creates.\n\nGit repositories support a number of additional options.\n\nbranch, tag, and ref\nYou  MUST  only  specify at most one of these options. The default is :branch => \"mas‐‐\nter\". For example:\n\ngem \"rails\", :git => \"https://github.com/rails/rails.git\", :branch => \"5-0-stable\"\n\ngem \"rails\", :git => \"https://github.com/rails/rails.git\", :tag => \"v5.0.0\"\n\ngem \"rails\", :git => \"https://github.com/rails/rails.git\", :ref => \"4aded\"\n"
                },
                {
                    "name": "submodules",
                    "content": "For reference,  a  git  submodule  https://git-scm.com/book/en/v2/Git-Tools-Submodules\nlets  you  have  another git repository within a subfolder of your repository. Specify\n:submodules => true to cause bundler to expand any  submodules  included  in  the  git\nrepository\n\nIf  a  git  repository contains multiple .gemspecs, each .gemspec represents a gem located at\nthe same place in the file system as the .gemspec.\n\n\n\n|~rails                   [git root]\n| |-rails.gemspec         [rails gem located here]\n|~actionpack\n| |-actionpack.gemspec    [actionpack gem located here]\n|~activesupport\n| |-activesupport.gemspec [activesupport gem located here]\n|...\n\n\n\nTo install a gem located in a git repository, bundler changes to the directory containing the\ngemspec,  runs gem build name.gemspec and then installs the resulting gem. The gem build com‐\nmand, which comes standard with Rubygems, evaluates the .gemspec in the context of the direc‐\ntory in which it is located.\n\nGIT SOURCE\nA custom git source can be defined via the gitsource method. Provide the source´s name as an\nargument, and a block which receives a single argument and interpolates it into a  string  to\nreturn the full repo address:\n\n\n\ngitsource(:stash){ |reponame| \"https://stash.corp.acme.pl/#{reponame}.git\" }\ngem ´rails´, :stash => ´forks/rails´\n\n\n\nIn addition, if you wish to choose a specific branch:\n\n\n\ngem \"rails\", :stash => \"forks/rails\", :branch => \"branchname\"\n\n\n\nGITHUB\nNOTE:  This  shorthand  should be avoided until Bundler 2.0, since it currently expands to an\ninsecure git:// URL. This allows a man-in-the-middle attacker to compromise your system.\n\nIf the git repository you want to use is hosted on GitHub and is  public,  you  can  use  the\n:github  shorthand  to  specify the github username and repository name (without the trailing\n\".git\"), separated by a slash. If both the username and repository name are the same, you can\nomit one.\n\n\n\ngem \"rails\", :github => \"rails/rails\"\ngem \"rails\", :github => \"rails\"\n\n\n\nAre both equivalent to\n\n\n\ngem \"rails\", :git => \"git://github.com/rails/rails.git\"\n\n\n\nSince  the  github method is a specialization of gitsource, it accepts a :branch named argu‐\nment.\n\nYou can also directly pass a pull request URL:\n\n\n\ngem \"rails\", :github => \"https://github.com/rails/rails/pull/43753\"\n\n\n\nWhich is equivalent to:\n\n\n\ngem \"rails\", :github => \"rails/rails\", branch: \"refs/pull/43753/head\"\n\n\n\nGIST\nIf the git repository you want to use is hosted as a GitHub Gist and is public, you  can  use\nthe :gist shorthand to specify the gist identifier (without the trailing \".git\").\n\n\n\ngem \"thehatch\", :gist => \"4815162342\"\n\n\n\nIs equivalent to:\n\n\n\ngem \"thehatch\", :git => \"https://gist.github.com/4815162342.git\"\n\n\n\nSince the gist method is a specialization of gitsource, it accepts a :branch named argument.\n\nBITBUCKET\nIf  the  git repository you want to use is hosted on Bitbucket and is public, you can use the\n:bitbucket shorthand to specify the bitbucket  username  and  repository  name  (without  the\ntrailing  \".git\"),  separated  by  a  slash. If both the username and repository name are the\nsame, you can omit one.\n\n\n\ngem \"rails\", :bitbucket => \"rails/rails\"\ngem \"rails\", :bitbucket => \"rails\"\n\n\n\nAre both equivalent to\n\n\n\ngem \"rails\", :git => \"https://rails@bitbucket.org/rails/rails.git\"\n\n\n\nSince the bitbucket method is a specialization of gitsource, it accepts a :branch named  ar‐\ngument.\n\nPATH\nYou  can  specify that a gem is located in a particular location on the file system. Relative\npaths are resolved relative to the directory containing the Gemfile.\n\nSimilar to the semantics of the :git option, the :path option requires that the directory  in\nquestion either contains a .gemspec for the gem, or that you specify an explicit version that\nbundler should use.\n\nUnlike :git, bundler does not compile C extensions for gems specified as paths.\n\n\n\ngem \"rails\", :path => \"vendor/rails\"\n\n\n\nIf you would like to use multiple local gems directly from the  filesystem,  you  can  set  a\nglobal  path option to the path containing the gem´s files. This will automatically load gem‐\nspec files from subdirectories.\n\n\n\npath ´components´ do\ngem ´adminui´\ngem ´publicui´\nend\n\n\n"
                },
                {
                    "name": "BLOCK FORM OF SOURCE, GIT, PATH, GROUP and PLATFORMS",
                    "content": "The :source, :git, :path, :group, and :platforms options may be applied to a group of gems by\nusing block form.\n\n\n\nsource \"https://gems.example.com\" do\ngem \"someinternalgem\"\ngem \"anotherinternalgem\"\nend\n\ngit \"https://github.com/rails/rails.git\" do\ngem \"activesupport\"\ngem \"actionpack\"\nend\n\nplatforms :ruby do\ngem \"ruby-debug\"\ngem \"sqlite3\"\nend\n\ngroup :development, :optional => true do\ngem \"wirble\"\ngem \"faker\"\nend\n\n\n\nIn the case of the group block form the :optional option can be given to prevent a group from\nbeing installed unless listed in the --with option given to the bundle install command.\n\nIn the case of the git block form, the :ref, :branch, :tag, and :submodules  options  may  be\npassed to the git method, and all gems in the block will inherit those options.\n\nThe  presence  of  a source block in a Gemfile also makes that source available as a possible\nglobal source for any other gems which do not specify explicit sources. Thus,  when  defining\nsource blocks, it is recommended that you also ensure all other gems in the Gemfile are using\nexplicit sources, either via source blocks or :source directives on individual gems.\n"
                }
            ]
        },
        "INSTALLIF": {
            "content": "The installif method allows gems to be installed based on a proc or lambda.  This  is  espe‐\ncially  useful  for  optional  gems that can only be used if certain software is installed or\nsome other conditions are met.\n\n\n\ninstallif -> { RUBYPLATFORM =~ /darwin/ } do\ngem \"pasteboard\"\nend\n\n\n",
            "subsections": []
        },
        "GEMSPEC": {
            "content": "The .gemspec http://guides.rubygems.org/specification-reference/ file is  where  you  provide\nmetadata  about  your gem to Rubygems. Some required Gemspec attributes include the name, de‐\nscription, and homepage of your gem. This is also where you specify the dependencies your gem\nneeds to run.\n\nIf  you  wish  to use Bundler to help install dependencies for a gem while it is being devel‐\noped, use the gemspec method to pull in the dependencies listed in the .gemspec file.\n\nThe gemspec method adds any runtime dependencies as gem requirements in the default group. It\nalso  adds development dependencies as gem requirements in the development group. Finally, it\nadds a gem requirement on your project (:path => ´´.´´).  In  conjunction  with  Bundler.setup,\nthis  allows  you to require project files in your test code as you would if the project were\ninstalled as a gem; you need not manipulate the load path manually or require  project  files\nvia relative paths.\n\nThe  gemspec  method  supports  optional :path, :glob, :name, and :developmentgroup options,\nwhich control where bundler looks for the .gemspec, the glob it uses to look for the  gemspec\n(defaults  to:  \"{,,/*}.gemspec\"), what named .gemspec it uses (if more than one is present),\nand which group development dependencies are included in.\n\nWhen a gemspec dependency encounters version conflicts during resolution, the  local  version\nunder  development  will  always be selected -- even if there are remote versions that better\nmatch other requirements for the gemspec gem.\n",
            "subsections": []
        },
        "SOURCE PRIORITY": {
            "content": "When attempting to locate a gem to satisfy a gem requirement, bundler uses the following pri‐\nority order:\n\n1.  The source explicitly attached to the gem (using :source, :path, or :git)\n\n2.  For  implicit  gems  (dependencies of explicit gems), any source, git, or path repository\ndeclared on the parent. This results in bundler prioritizing the ActiveSupport  gem  from\nthe Rails git repository over ones from rubygems.org\n\n3.  The sources specified via global source lines, searching each source in your Gemfile from\nlast added to first added.\n\n\n\n\n\n\nDecember 2021                                 GEMFILE(5)",
            "subsections": []
        }
    },
    "summary": "Gemfile - A format for describing gem dependencies for Ruby programs",
    "flags": [],
    "examples": [],
    "see_also": []
}