{
    "mode": "man",
    "parameter": "Gemfile",
    "section": "5",
    "url": "https://www.chedong.com/phpMan.php/man/Gemfile/5/json",
    "generated": "2026-10-12T11:32:56Z",
    "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 SOURCE": {
            "content": "At  the  top of the Gemfile, add a single line for the RubyGems source that contains the gems\nlisted in the Gemfile.\n\n\n\nsource \"https://rubygems.org\"\n\n\n\nYou can add only one global source. In Bundler 1.13, adding multiple global sources was  dep‐\nrecated. The source MUST be a valid RubyGems repository.\n\nTo use more than one source of RubyGems, you should use source block.\n\nA source is checked for gems following the heuristics described in SOURCE PRIORITY.\n\nNote  about  a  behavior of the feature deprecated in Bundler 1.13: If a gem is found in more\nthan one global source, Bundler will print a warning  after  installing  the  gem  indicating\nwhich  source  was used, and listing the other sources where the gem is available. A specific\nsource can be selected for gems that need to use a non-standard repository, suppressing  this\nwarning, by using the :source option or 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, TruffleRuby, etc., this should be the Ruby version that  the  en‐\ngine is compatible with.\n\n\n\nruby \"3.1.2\"\n\n\n\nIf  you  wish to derive your Ruby version from a version file (ie .ruby-version), you can use\nthe file option instead.\n\n\n\nruby file: \".ruby-version\"\n\n\n\nThe version file should conform to any of the following formats:\n\n•   3.1.2 (.ruby-version)\n\n•   ruby 3.1.2 (.tool-versions, read: https://asdf-vm.com/manage/configuration.html#tool-ver‐\nsions)\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   JRuby    http://jruby.org/    and    TruffleRuby\nhttps://www.graalvm.org/ruby/.  Rubinius is an alternative implementation of Ruby written\nin Ruby. JRuby is an implementation of Ruby on the JVM, short for Java  Virtual  Machine.\nTruffleRuby is a Ruby implementation on the GraalVM, a language toolkit built on the JVM.\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 \"2.6.8\", engine: \"jruby\", engineversion: \"9.3.8.0\"\n\n\n\nPATCHLEVEL\nEach application may specify a Ruby patchlevel. Specifying the patchlevel has  been  meaning‐\nless since Ruby 2.1.0 was released as the patchlevel is now uniquely determined by a combina‐\ntion of major, minor, and teeny version numbers.\n\nThis option was implemented in Bundler 1.4.0 for Ruby 2.0 or earlier.\n\n\n\nruby \"3.1.2\", patchlevel: \"20\"\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    C Ruby (MRI) only, but not Windows\n"
                },
                {
                    "name": "windows",
                    "content": "Windows C Ruby (MRI), including RubyInstaller 32-bit and 64-bit versions\n\nmswin  Windows C Ruby (MRI), including RubyInstaller 32-bit versions\n"
                },
                {
                    "name": "mswin64",
                    "content": "Windows C Ruby (MRI), including RubyInstaller 64-bit versions\n\nrbx    Rubinius\n\njruby  JRuby\n"
                },
                {
                    "name": "truffleruby",
                    "content": "TruffleRuby\n\nOn platforms ruby, mri, mswin, mswin64, and windows, you may additionally specify  a  version\nby appending the major and minor version numbers without a delimiter. For example, to specify\nthat a gem should only be used on platform ruby version 3.1, use:\n\n\n\nruby31\n\n\n\nAs with groups (above), you may specify one or more platforms:\n\n\n\ngem \"weakling\",   platforms: :jruby\ngem \"ruby-debug\", platforms: :mri31\ngem \"nokogiri\",   platforms: [:windows31, :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\nFORCERUBYPLATFORM\nIf  you  always want the pure ruby variant of a gem to be chosen over platform specific vari‐\nants, you can use the forcerubyplatform option:\n\n\n\ngem \"ffi\", forcerubyplatform: true\n\n\n\nThis can be handy (assuming the pure ruby variant works fine) when:\n\n•   You´re having issues with the platform specific variant.\n\n•   The platform specific variant does not yet support a newer  ruby  (and  thus  has  a  re‐\nquiredrubyversion upper bound), but you still want your Gemfile{.lock} files to resolve\nunder that ruby.\n\n\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 the global source 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  the  global\nsource.\n\nNote  about a behavior of the feature deprecated in Bundler 1.13: Selecting a specific source\nrepository this way also suppresses the ambiguous  gem  warning  described  above  in  GLOBAL\nSOURCE.\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: \"master\".\nFor 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\nsubmodules: true to cause bundler to expand any submodules included in the git reposi‐\ntory\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: \"https://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\nBLOCK FORM OF SOURCE, GIT, PATH, GROUP and PLATFORMS\nThe :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, this\nallows you to require project files in your test code as you would if the  project  were  in‐\nstalled as a gem; you need not manipulate the load path manually or require project files via\nrelative 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.  If neither of the above conditions are met, the global source will be used.  If  multiple\nglobal  sources  are  specified, they will be prioritized from last to first, but this is\ndeprecated since Bundler 1.13, so Bundler prints a warning and will abort with  an  error\nin the future.\n\n\n\n\nAugust 2023                                  GEMFILE(5)",
            "subsections": []
        }
    },
    "summary": "Gemfile - A format for describing gem dependencies for Ruby programs",
    "flags": [],
    "examples": [],
    "see_also": []
}