# RubyGems Guides

> Everything about library management in Ruby: learn what gems are, how to use them in your projects, and how to build and publish your own.

Ruby libraries are packaged and distributed as gems. RubyGems installs individual gems and provides the `gem` command, and Bundler tracks the exact set of gems an application depends on through a `Gemfile`. Both ship with Ruby. Gems are published and downloaded on [RubyGems.org](https://rubygems.org). These guides cover both tools and the RubyGems.org APIs.

## Getting Started

- [Installation](https://guides.rubygems.org/installation.md): How to get RubyGems and Bundler and keep them up to date.
- [RubyGems Basics](https://guides.rubygems.org/rubygems-basics.md): Use of common RubyGems commands
- [Getting Started with Bundler](https://guides.rubygems.org/getting_started.md): First steps with Bundler: declare dependencies in a Gemfile and run your code with them.
- [Make your own gem](https://guides.rubygems.org/make-your-own-gem.md): From start to finish, learn how to package your Ruby code in a gem.
- [Publishing your gem](https://guides.rubygems.org/publishing.md): Start with an idea, end with a distributable package of Ruby code.

## Dependency Management

- [How to manage application dependencies with Bundler](https://guides.rubygems.org/using_bundler_in_applications.md): The day-to-day Bundler workflow for applications, from installing to updating and version control.
- [How to manage dependencies with Bundler](https://guides.rubygems.org/dependency_management.md): Why applications declare dependencies in a Gemfile and how Bundler keeps them consistent.
- [How to update gems with Bundler](https://guides.rubygems.org/updating_gems.md): Update the gems in a bundle, one at a time or all at once.
- [How to manage groups of gems](https://guides.rubygems.org/groups.md): Organize Gemfile dependencies into groups you can install or require selectively.
- [How to install gems from git repositories](https://guides.rubygems.org/git.md): Declare dependencies on gems that live in git repositories.
- [How to develop multiple gems in one repository](https://guides.rubygems.org/monorepo.md): Using path gems to develop a family of related gems side by side.
- [How to use Bundler with Ruby](https://guides.rubygems.org/bundler_setup.md): What require "bundler/setup" does and how to load the bundled environment in plain Ruby code.
- [How to use Bundler in a single-file Ruby script](https://guides.rubygems.org/bundler_in_a_single_file_ruby_script.md): Declare a script's dependencies inline with bundler/inline instead of a separate Gemfile.
- [How to deploy bundled applications](https://guides.rubygems.org/deploying.md): Install a bundle reproducibly on servers and in CI with deployment mode.

## Gem Development

- [Name your gem](https://guides.rubygems.org/name-your-gem.md): Our recommendation on the use of "_" and "-" in your gem's name.
- [Patterns](https://guides.rubygems.org/patterns.md): Common practices to make your gem users' and other developers' lives easier.
- [Gems with Extensions](https://guides.rubygems.org/gems-with-extensions.md): Creating a gem that includes an extension that is built at install time.
- [Bundler in gems](https://guides.rubygems.org/rubygems.md): Using Bundler during gem development with the gemspec directive.

## Publishing & Security

- [Trusted Publishing](https://guides.rubygems.org/trusted-publishing.md): Publish gems from CI without long-lived API keys using OpenID Connect.
- [Setting up multi-factor authentication](https://guides.rubygems.org/setting-up-multifactor-authentication.md): Want to better protect your RubyGems.org account?
- [Using multi-factor authentication in command line](https://guides.rubygems.org/using-mfa-in-command-line.md): How to use multi-factor authentication with gem CLI.
- [Managing owners using UI](https://guides.rubygems.org/managing-owners-using-ui.md): How to add or remove owners to your gem using the web UI?
- [Organizations](https://guides.rubygems.org/organizations.md): What RubyGems.org organizations are and how they help teams manage gems together.
- [Getting Started](https://guides.rubygems.org/organizations/getting-started.md): Create an organization on RubyGems.org and move your gems into it.
- [Managing Members](https://guides.rubygems.org/organizations/managing-members.md): Invite, update, and remove members of a RubyGems.org organization.
- [Roles & Permissions](https://guides.rubygems.org/organizations/roles-and-permissions.md): What each organization role can and cannot do.
- [Transferring Gems](https://guides.rubygems.org/organizations/transferring-gems.md): Move existing gems into a RubyGems.org organization.
- [Removing a Published gem](https://guides.rubygems.org/removing-a-published-gem.md): Published a gem before it was ready for release? Published a gem with the wrong name?
- [Security Practices](https://guides.rubygems.org/security.md): How to protect your account as a gem author, harden the gems you install, and report vulnerabilities.
- [How to delay new gem versions with cooldown](https://guides.rubygems.org/cooldown.md): How to keep Bundler from resolving to gem versions published in the last few days.

## Integrations

- [How to use Bundler with Rails](https://guides.rubygems.org/rails.md): Set up and use Bundler in a Rails application.
- [How to use Bundler with Sinatra](https://guides.rubygems.org/sinatra.md): Set up and use Bundler in a Sinatra application.
- [How to use Bundler with Docker](https://guides.rubygems.org/bundler_docker_guide.md): Build Docker images for bundled Ruby applications, including private gem sources.
- [How to use Bundler in CI](https://guides.rubygems.org/ci.md): How to install gems quickly and reproducibly on GitHub Actions, GitLab CI, and other CI systems.

## Hosting & Sources

- [Run your own gem server](https://guides.rubygems.org/run-your-own-gem-server.md): Need to serve gems locally or for your organization?
- [Using S3 as gem source](https://guides.rubygems.org/using-s3-source.md): How to use S3 bucket as gem source.

## Extending

- [RubyGems Plugins](https://guides.rubygems.org/plugins.md): Extensions that use the RubyGems plugin API.
- [How to write a Bundler plugin](https://guides.rubygems.org/bundler_plugins.md): Extend Bundler with new commands, gem sources, and lifecycle hooks.

## Troubleshooting

- [Troubleshooting common issues](https://guides.rubygems.org/troubleshooting.md): What to do when a gem fails to build, dependencies will not resolve, or you are not sure what is broken.
- [How to troubleshoot RubyGems and Bundler TLS/SSL Issues](https://guides.rubygems.org/rubygems_tls_ssl_troubleshooting_guide.md): What `certificate verify failed` means and how to fix it.
- [How to use git bisect with Bundler](https://guides.rubygems.org/git_bisect.md): Track down regressions across gem versions with git bisect and Bundler.

## Concepts

- [What is a gem?](https://guides.rubygems.org/what-is-a-gem.md): Unpack the mystery behind what's in a RubyGem.
- [Gemfile and gemspec](https://guides.rubygems.org/gemfile-and-gemspec.md): Which file your dependencies belong in, and why Ruby projects have two of them.
- [Where gems are installed and how they load](https://guides.rubygems.org/gem-installation-and-loading.md): How RubyGems decides where a gem lives on disk, and what happens when you require it.
- [How dependency resolution works](https://guides.rubygems.org/dependency-resolution.md): How Bundler picks one set of gem versions that satisfies your Gemfile and every gemspec at once.
- [How Gemfile.lock works](https://guides.rubygems.org/gemfile-lock.md): How to read the file that pins every gem version your application installs.
- [Versioning and compatibility](https://guides.rubygems.org/versioning.md): What a version number can and cannot promise, and how RubyGems compares and constrains versions.
- [Platforms and native gems](https://guides.rubygems.org/platforms.md): How RubyGems names the system a gem was built for, and how precompiled native gems skip compilation at install time.
- [Caching and vendoring](https://guides.rubygems.org/caching-and-vendoring.md): The caches RubyGems and Bundler keep on your machine, and how to vendor an application’s gems for installs that need no network.
- [Default gems and bundled gems](https://guides.rubygems.org/default-gems-and-bundled-gems.md): Understanding Ruby’s standard library gems.
- [Common Vulnerabilities and Exposures](https://guides.rubygems.org/cve.md): How security vulnerabilities in RubyGems are reported, tracked, and disclosed.

## Reference

- [gem Command Reference](https://guides.rubygems.org/command-reference.md): What each gem command does, and how to use it.
- [Bundler Command Reference](https://guides.rubygems.org/command-reference/bundle/): Ruby Dependency Management
- [Gemfile Reference](https://guides.rubygems.org/gemfile/): A format for describing gem dependencies for Ruby programs
- [Ruby Directive](https://guides.rubygems.org/gemfile_ruby.md): Pin the Ruby version an application requires with the Gemfile ruby directive.
- [Specification Reference](https://guides.rubygems.org/specification-reference.md): Every attribute of Gem::Specification, generated from the RubyGems source.
- [RubyGems.org API](https://guides.rubygems.org/rubygems-org-api.md): Details on interacting with RubyGems.org over HTTP.
- [RubyGems.org Compact Index API](https://guides.rubygems.org/rubygems-org-compact-index-api.md): Details of the Compact Index API used for Bundler dependency resolution
- [RubyGems.org rate limits](https://guides.rubygems.org/rubygems-org-rate-limits.md): Why are you seeing 429 responses?
- [API key scopes](https://guides.rubygems.org/api-key-scopes.md): RubyGems.org API keys, their scopes, and CLI usage
- [Bundler compatibility with Ruby](https://guides.rubygems.org/bundler-compatibility.md): Which Bundler versions work with which Ruby and RubyGems versions.
- [Configuration (.gemrc)](https://guides.rubygems.org/configuration.md): Where the gem command reads its configuration, and the options a .gemrc file accepts.
- [Environment variables](https://guides.rubygems.org/environment-variables.md): The environment variables the gem command and the RubyGems runtime respond to.
- [Known Bundler Plugins](https://guides.rubygems.org/bundler_known_plugins.md): A list of known Bundler plugins and what they do.

## Appendix

- [Frequently Asked Questions](https://guides.rubygems.org/faqs.md): More of the “why” and “wtf” than “how”.
- [Glossary](https://guides.rubygems.org/glossary.md): Definitions of the terms used throughout these guides.
- [Contributing to RubyGems](https://guides.rubygems.org/contributing.md): How you can help make RubyGems and the surrounding ecosystem better.
- [Credits](https://guides.rubygems.org/credits.md): This site is open source and its content is Creative Commons licensed.