gem Operations

The gem module manages Ruby gem packages.

This module assumes that gem (RubyGems) is already installed on the system.

Functions

packages

Install, remove, or update gem packages.

from pyinfra.operations import gem

gem.packages(
    name="Install Ruby gems",
    packages=["rails", "bundler"],
)

str | list[str]

List of packages to ensure.

bool

default:true

Whether the packages should be installed.

bool

default:false

Whether to upgrade packages without a specified version.

Package versions can be pinned like gem: <pkg>:<version>

Examples

from pyinfra.operations import gem

# Note: Assumes that 'gem' is installed.
gem.packages(
    name="Install rspec",
    packages=["rspec"],
)

from pyinfra.operations import gem

gem.packages(
    name="Install Rails and dependencies",
    packages=[
        "rails",
        "bundler",
        "puma",
        "pg",
    ],
)

from pyinfra.operations import gem

gem.packages(
    name="Install specific gem versions",
    packages=[
        "rails:7.0.4",
        "bundler:2.4.10",
    ],
)

from pyinfra.operations import gem

gem.packages(
    name="Install latest gems",
    packages=["rails", "rspec"],
    latest=True,
)

Common Use Cases

Rails Application Setup

from pyinfra.operations import gem

gem.packages(
    name="Install Rails stack",
    packages=[
        "rails",
        "bundler",
        "puma",
        "pg",
        "redis",
    ],
)

Development Tools

from pyinfra.operations import gem

gem.packages(
    name="Install Ruby development tools",
    packages=[
        "rubocop",
        "rspec",
        "pry",
        "bundler-audit",
    ],
)

Static Site Generator

from pyinfra.operations import gem

gem.packages(
    name="Install Jekyll",
    packages=[
        "jekyll",
        "bundler",
    ],
)

Install Specific Rails Version

from pyinfra.operations import gem

gem.packages(
    name="Install Rails 7",
    packages=["rails:7.0.4"],
)

Testing Framework

from pyinfra.operations import gem

gem.packages(
    name="Install RSpec and tools",
    packages=[
        "rspec",
        "rspec-rails",
        "factory_bot",
        "faker",
    ],
)

Ruby Gem Tips

Using Bundler

For Ruby projects, use Bundler to manage dependencies:

from pyinfra.operations import gem, files, server

# Install bundler
gem.packages(
    name="Install Bundler",
    packages=["bundler"],
)

# Upload Gemfile
files.put(
    name="Upload Gemfile",
    src="local/Gemfile",
    dest="/app/Gemfile",
)

# Install gems from Gemfile
server.shell(
    name="Install gems with Bundler",
    commands=["cd /app && bundle install"],
)

System vs User Gems

System gems (default):

Installed globally
May require sudo

User gems (with —user-install):

Installed in user’s home directory
No sudo required

from pyinfra.operations import server

# Install as user
server.shell(
    name="Install gem as user",
    commands=["gem install rails --user-install"],
)

Update All Gems

Update all installed gems:

from pyinfra.operations import server

server.shell(
    name="Update all gems",
    commands=["gem update"],
)

List Installed Gems

View installed gems:

from pyinfra.operations import server

server.shell(
    name="List installed gems",
    commands=["gem list"],
)

Clean Up Old Versions

Remove old gem versions:

from pyinfra.operations import server

server.shell(
    name="Clean up old gem versions",
    commands=["gem cleanup"],
)

Custom Gem Sources

Add custom gem sources:

from pyinfra.operations import server

server.shell(
    name="Add custom gem source",
    commands=[
        "gem sources --add https://gems.company.com",
    ],
)

Best Practices

Use Bundler for Projects

from pyinfra.operations import gem, files, server

# Install bundler
gem.packages(
    name="Install Bundler",
    packages=["bundler"],
)

# Use Gemfile and Gemfile.lock
files.put(
    name="Upload Gemfile",
    src="local/Gemfile",
    dest="/app/Gemfile",
)

files.put(
    name="Upload Gemfile.lock",
    src="local/Gemfile.lock",
    dest="/app/Gemfile.lock",
)

# Install exact versions
server.shell(
    name="Bundle install",
    commands=["cd /app && bundle install --deployment"],
)

Pin Important Versions

from pyinfra.operations import gem

gem.packages(
    name="Install with pinned versions",
    packages=[
        "rails:7.0.4",
        "bundler:2.4.10",
    ],
)

Install System Dependencies First

from pyinfra.operations import apt, gem

# Install system dependencies
apt.packages(
    name="Install Ruby and dependencies",
    packages=[
        "ruby-full",
        "build-essential",
        "libpq-dev",  # For pg gem
        "libsqlite3-dev",  # For sqlite3 gem
    ],
)

# Then install gems
gem.packages(
    name="Install Ruby gems",
    packages=["rails", "pg"],
)

Important Notes

Installing gems system-wide may require sudo/root privileges. Consider using Bundler for project-specific gem management.

Gem version pinning uses : (colon) as the separator, not == like pip or @ like npm.

For production Rails applications, always use Bundler with --deployment flag to ensure consistent gem versions.

Overview

Package Managers

Language Packages

Service Management

System Operations

Containers

Databases

Version Control

Security

Functions

packages

Examples

Common Use Cases

Rails Application Setup

Development Tools

Static Site Generator

Install Specific Rails Version

Testing Framework

Ruby Gem Tips

Best Practices

Important Notes

​Functions

​packages

​Examples

​Common Use Cases

​Rails Application Setup

​Development Tools

​Static Site Generator

​Install Specific Rails Version

​Testing Framework

​Ruby Gem Tips

​Best Practices

​Important Notes

Functions

packages

Examples

Common Use Cases

Rails Application Setup

Development Tools

Static Site Generator

Install Specific Rails Version

Testing Framework

Ruby Gem Tips

Best Practices

Important Notes