What is a gem?
A gem is a packaged Ruby library or tool. Instead of writing every feature yourself, you can add a maintained library for a specific task, such as formatting terminal text or testing code. Some gems provide code you load with require; others also provide commands. Ruby’s own language features and a third-party gem are different things.
RubyGems is the package-management system that finds, installs and manages gems. The gem command comes with ordinary Ruby installations. RubyGems.org hosts public gems, but a gem can also come from another source. Installing an external package means trusting code you did not write, so read its documentation, supported Ruby versions and maintenance information before depending on it.
Inspect and install a gem
Open a local terminal and run gem --version to check RubyGems. gem list --local lists gems available to the Ruby selected by this terminal, including gems supplied with Ruby. gem list rainbow narrows the list to matching installed names. The exact list varies by installation. Installing with gem install rainbow adds the Rainbow gem to that Ruby’s gem environment; it does not declare the dependency for a particular project.
Use gem install for a quick local experiment or a tool you intentionally install outside a project. For a project you will keep or share, record dependencies in a Gemfile and use Bundler. If an installation fails with permissions or native-extension errors, first check which Ruby is selected and use your platform setup guide; do not treat sudo gem install or changing system-folder ownership as a routine fix.
Terminal — inspect RubyGems and installed gems
gem --version
gem list --local
gem list rainbowTerminal — optional standalone installation
gem install rainbowWhy a project uses Bundler
Bundler manages one project’s set of gems. A Gemfile at the project root names the direct gems and their source; Bundler also resolves the gems those packages need. Gemfile.lock records the exact resolved versions and platforms. The Gemfile describes what the project is allowed to use, while the lockfile records the particular set that worked together when it was generated.
Check bundle --version before starting. Modern Ruby distributions usually include Bundler, but some system packages split tools into separate packages. If bundle is missing, follow your Ruby distribution’s or RubyGems’ official installation guidance. You do not need to add Bundler or Rainbow to Codectionary’s own package.json to follow this guide: these commands concern a separate local Ruby practice project.
Terminal — verify Bundler
bundle --versionTry a small project with Rainbow
Make a new folder, for example ruby-colour-demo, and put the two files below inside it. The Gemfile declares RubyGems.org as the source and Rainbow as the project’s direct dependency. Rainbow is a small gem for applying ANSI colour to terminal text. The hello.rb file loads the gem with require and passes a blue-presented String to puts. The words Hello, Codectionary! appear in the terminal; their colour depends on whether that terminal supports ANSI colour.
From that folder, run bundle install. Bundler reads the Gemfile, resolves compatible versions, installs the needed gems and writes Gemfile.lock. Then run bundle exec ruby hello.rb. bundle exec starts ruby in the project’s resolved gem environment, so require loads the version selected for this project rather than an unrelated version available elsewhere. Ruby executes the file and puts prints the text. You need network access for a first installation unless the needed gems are already cached.
Gemfile — save at the project root
source "https://rubygems.org"
gem "rainbow"hello.rb — save beside Gemfile
require "rainbow"
puts Rainbow("Hello, Codectionary!").blueTerminal — run from the project folder
bundle install
bundle exec ruby hello.rbWhy versions and a lockfile matter
A later version of a gem can change behaviour, APIs or supported Ruby versions. A Gemfile can express a version rule when the project needs one; without an explicit rule, Bundler chooses a compatible release available at the first resolution. Gemfile.lock then records exact direct and transitive versions. Running bundle install again normally reuses that lock rather than silently selecting every newly published gem.
For an application you run or deploy, keep Gemfile and Gemfile.lock together in version control so teammates use the same resolved dependencies. Do not hand-edit the lockfile. Updating a gem is a deliberate step that needs testing. If you are publishing a reusable gem library, its runtime dependencies belong in a gemspec and lockfile policy differs because consumers resolve dependencies in their own applications.
Know what each command does
gem list inspects installed gems; gem install installs a gem into the selected Ruby environment. bundle install reads the project Gemfile and makes its resolved dependencies available. bundle exec runs a command with that bundle active; it does not install anything by itself. ruby hello.rb executes a saved source file. These commands have different jobs even when they appear together in a tutorial.
If require reports that it cannot load rainbow, check that you are in the folder with the Gemfile, that bundle install completed, and that you used bundle exec ruby hello.rb. If Bundler reports a version conflict, read which gem requirements disagree rather than deleting Gemfile.lock blindly. For a system-managed Ruby, resolve permission errors by selecting an independently managed Ruby as explained in the installation guides.
Syntax
gem list
bundle install
bundle exec ruby hello.rbExamples
A project dependency in use
With Rainbow declared in Gemfile and installed by bundle install, run this saved file with bundle exec ruby hello.rb.
require "rainbow"
puts Rainbow("Hello, Codectionary!").blue- The Gemfile declares rainbow as a direct dependency and Gemfile.lock records the selected version after bundle install.
- require loads the gem into this Ruby process. Rainbow(...).blue wraps the greeting in terminal colour formatting.
- puts sends the greeting to standard output; bundle exec makes the project’s resolved gem version available. The text remains readable even if colour is unavailable.
Best practices
- Declare application dependencies in a Gemfile and keep its generated lockfile.
- Run project commands in the Bundler context when they depend on bundled gems.
- Check a gem’s source, version support and maintenance before adding it.
Runtime & versions
Ruby interpreter. Feature availability depends on the language and runtime version used by your project; consult the official reference below.
Ruby documentation