# How to manage Rails dependencies in Replit

- Tool: Replit
- Difficulty: Beginner
- Time required: 20-30 minutes
- Compatibility: Replit Core or Pro plan recommended for sufficient RAM (8 GiB). Starter plan (2 GiB) may struggle with larger Rails apps.
- Last updated: March 2026

## TL;DR

Manage Ruby on Rails dependencies in Replit by configuring Ruby and Bundler through the replit.nix file for system-level packages, editing the Gemfile for Rails gems, and running bundle install from the Shell. Configure the .replit file with the correct run command and port binding to 0.0.0.0 for the Rails server. Replit's Nix environment gives you full control over Ruby versions and native dependencies.

## Set Up and Manage Rails Gem Dependencies on Replit

Ruby on Rails applications depend on a rich ecosystem of gems managed by Bundler. Running Rails on Replit requires configuring both the Nix system environment for Ruby and native libraries, and the Gemfile for application-level gems. This tutorial walks you through setting up a complete Rails development environment on Replit, managing gems with Bundler, handling native extensions that require system libraries, and configuring the .replit file for correct server startup.

## Before you start

- A Replit account (Core or Pro recommended for RAM)
- A Ruby on Rails Repl or a blank Repl you will configure for Rails
- Basic familiarity with Ruby syntax and Gemfile format
- Understanding of Replit's Shell tab and file tree

## Step-by-step guide

### 1. Configure replit.nix with Ruby and system dependencies

Replit uses Nix to manage system-level packages including the Ruby interpreter itself. Open the file tree, enable Show hidden files from the three-dot menu, and edit the replit.nix file. Add the Ruby package, Bundler, and any system libraries your gems need (such as PostgreSQL client libraries for the pg gem, or ImageMagick for image processing). After editing replit.nix, type exit in the Shell to restart the environment and load the new packages. Search for available packages at search.nixos.org/packages if you need additional system dependencies.

```
# replit.nix
{ pkgs }: {
  deps = [
    pkgs.ruby_3_2
    pkgs.bundler
    pkgs.postgresql
    pkgs.libffi
    pkgs.zlib
    pkgs.openssl
    pkgs.libyaml
    pkgs.pkg-config
    pkgs.nodejs-20_x
  ];
}
```

**Expected result:** After typing exit in the Shell and reopening it, running ruby --version shows the installed Ruby version and bundle --version shows Bundler is available.

### 2. Create and configure the Gemfile

The Gemfile lists all Ruby gems your Rails application depends on. If you are starting from scratch, create a Gemfile in your project root. If you imported an existing Rails project, the Gemfile already exists. Add your gems with version constraints. Use pessimistic version constraints (~>) for most gems to allow minor updates while preventing breaking major changes. After editing the Gemfile, run bundle install in the Shell to download and install all listed gems. Bundler creates a Gemfile.lock that pins exact versions for reproducibility.

```
# Gemfile
source 'https://rubygems.org'

ruby '3.2.2'

gem 'rails', '~> 7.1'
gem 'pg', '~> 1.5'
gem 'puma', '~> 6.0'
gem 'jbuilder', '~> 2.11'
gem 'bcrypt', '~> 3.1'
gem 'bootsnap', require: false

group :development, :test do
  gem 'debug', platforms: [:mri]
  gem 'rspec-rails', '~> 6.0'
end

group :development do
  gem 'web-console'
end
```

**Expected result:** Running bundle install in the Shell downloads all gems and their dependencies. The output shows 'Bundle complete!' with the number of gems installed.

### 3. Handle gems with native extensions

Some gems like pg (PostgreSQL), nokogiri (XML parsing), and mini_magick (image processing) require native C libraries to compile their extensions. When bundle install fails with an error about missing headers or libraries, you need to add the corresponding Nix package to replit.nix. The error message usually tells you which library is missing. Common mappings: pg needs pkgs.postgresql, nokogiri needs pkgs.libxml2 and pkgs.libxslt, mini_magick needs pkgs.imagemagick, and bcrypt needs pkgs.libffi. After adding the Nix package, type exit in the Shell, reopen it, and run bundle install again.

```
# If you see: "Can't find the 'libpq-fe.h header"
# Add to replit.nix: pkgs.postgresql

# If you see: "Could not find libxml2"
# Add to replit.nix: pkgs.libxml2 and pkgs.libxslt

# If bundle install still fails after adding Nix packages,
# try configuring the build with bundle config:
bundle config build.pg --with-pg-config=$(which pg_config)
bundle config build.nokogiri --use-system-libraries

# Then retry:
bundle install
```

**Expected result:** Native gems compile successfully after adding the required system libraries to replit.nix. bundle install completes without compilation errors.

### 4. Configure the .replit file for Rails server

The .replit file tells Replit how to run your application. For Rails, set the run command to start the Puma server bound to 0.0.0.0 on port 3000. Binding to 0.0.0.0 is critical because Replit's preview panel and deployments cannot reach a server bound to localhost or 127.0.0.1. Configure the port mapping so Replit's external port 80 maps to your local port 3000. Also set the deployment commands for production builds.

```
# .replit
entrypoint = "config/routes.rb"
run = "bundle exec rails server -b 0.0.0.0 -p 3000"

[nix]
channel = "stable-23_11"

[[ports]]
localPort = 3000
externalPort = 80

[deployment]
build = "bundle install && bundle exec rails assets:precompile"
run = ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000", "-e", "production"]
```

**Expected result:** Clicking the Run button starts the Rails server on port 3000. The Replit Preview panel loads your Rails application. Deployment commands build assets and start the production server.

### 5. Update gems and manage versions over time

Keep your gems current by periodically running bundle outdated in the Shell to see which gems have newer versions available. Update specific gems with bundle update gem-name or update all gems with bundle update (use with caution). For major Rails version upgrades, follow the official Rails upgrade guide and update one major version at a time. Always test your application after gem updates by running your test suite with bundle exec rspec or bundle exec rails test, and check the Console for deprecation warnings.

```
# Check for outdated gems
bundle outdated

# Update a specific gem
bundle update puma

# Update all gems (use carefully)
bundle update

# Run tests after updating
bundle exec rspec

# Check for security vulnerabilities
bundle audit check --update
```

**Expected result:** bundle outdated shows gems with available updates. After updating, bundle exec rspec confirms all tests still pass. The Gemfile.lock reflects the new gem versions.

## Complete code example

File: `.replit`

```toml
# Replit configuration for Ruby on Rails
entrypoint = "config/routes.rb"
run = "bundle exec rails server -b 0.0.0.0 -p 3000"

[nix]
channel = "stable-23_11"
packages = ["ruby_3_2", "bundler", "postgresql", "nodejs-20_x", "yarn", "libffi", "zlib", "openssl", "libyaml", "pkg-config"]

hidden = [".config", "vendor", "tmp", "log"]

[[ports]]
localPort = 3000
externalPort = 80

[run.env]
RAILS_ENV = "development"

[deployment]
build = "bundle install --without development test && bundle exec rails assets:precompile && bundle exec rails db:migrate"
run = ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000", "-e", "production"]

# Database URL and SECRET_KEY_BASE must be set in
# Tools > Secrets for deployment to work.
# Never hardcode these values in the .replit file.
```

## Common mistakes

- **Running rails server without -b 0.0.0.0, causing the Preview panel to show a blank page or connection refused error** — undefined Fix: Always include -b 0.0.0.0 in the run command: bundle exec rails server -b 0.0.0.0 -p 3000. This binds the server to all network interfaces.
- **Not adding system libraries to replit.nix before running bundle install, causing native gem compilation to fail with missing header errors** — undefined Fix: Read the error message to identify the missing library, add the corresponding Nix package to replit.nix, type exit in Shell to reload the environment, then run bundle install again.
- **Forgetting to set deployment secrets separately from workspace secrets, causing Rails to fail with 'Missing secret_key_base' in production** — undefined Fix: Add SECRET_KEY_BASE and DATABASE_URL in both the workspace Secrets and the Deployment pane secrets. Workspace secrets do not automatically carry to deployments.
- **Running gem install instead of adding gems to the Gemfile and running bundle install, causing version conflicts and unreproducible environments** — undefined Fix: Always add gems to the Gemfile with a version constraint and use bundle install. This ensures Bundler manages versions consistently and creates an accurate Gemfile.lock.
- **Using an outdated Nix channel that does not have the Ruby version needed, leading to installation failures** — undefined Fix: Update the channel in .replit to a recent stable version like stable-23_11 or newer. Check search.nixos.org for available Ruby versions in each channel.

## Best practices

- Always configure replit.nix with the required system libraries before running bundle install to avoid native extension compilation failures
- Bind the Rails server to 0.0.0.0 instead of localhost so Replit's Preview panel and deployments can access it
- Commit both Gemfile and Gemfile.lock to Git for reproducible gem installations across environments
- Use pessimistic version constraints (~>) in the Gemfile to allow minor updates while preventing breaking major changes
- Store DATABASE_URL, SECRET_KEY_BASE, and RAILS_MASTER_KEY in Replit Secrets (Tools > Secrets), never in code
- Run bundle exec before Rails commands to ensure you use the exact gem versions specified in your Gemfile.lock
- Add the vendor/bundle directory to .gitignore since gems should be installed fresh from the Gemfile, not committed
- Use bundle audit regularly to check your dependencies for known security vulnerabilities

## Frequently asked questions

### Can I run Rails on Replit's free Starter plan?

Technically yes, but the Starter plan's 2 GiB RAM is tight for Rails applications. Rails itself uses significant memory, and adding gems like Devise or Sidekiq can push you past the limit. Core or Pro plans with 8 GiB RAM are recommended.

### How do I use PostgreSQL with Rails on Replit?

Replit provides a built-in PostgreSQL database. Add it from the Cloud tab (click + next to Preview). The DATABASE_URL environment variable is automatically created. Add gem 'pg' to your Gemfile, run bundle install, and configure config/database.yml to use ENV['DATABASE_URL'].

### Why does bundle install fail with 'ERROR: Failed to build gem native extension'?

The gem requires system libraries that are not installed in the Nix environment. Read the error output to identify the missing library (e.g., libpq-fe.h for pg, libxml2 for nokogiri), add the corresponding package to replit.nix, exit and reopen the Shell, then run bundle install again.

### How do I run Rails database migrations on Replit?

Run bundle exec rails db:migrate in the Shell tab. For deployment, add it to your deployment build command in .replit: build = 'bundle install && bundle exec rails db:migrate && bundle exec rails assets:precompile'.

### Can Replit Agent build a Rails application?

Replit Agent supports Rails, though React + Tailwind + ShadCN UI is the best-supported stack. Agent can scaffold Rails projects, generate models and controllers, and configure database connections. For complex Rails configurations, RapidDev's engineering team provides hands-on development support.

### How do I access the Rails console on Replit?

Open the Shell tab and run bundle exec rails console. This gives you an interactive Ruby session with your Rails application loaded, useful for testing queries, debugging data, and running one-off scripts.

### Where should I store Rails secrets like SECRET_KEY_BASE?

Use Replit Secrets (Tools > Secrets in the left sidebar). Add SECRET_KEY_BASE, DATABASE_URL, and any API keys there. Access them in Rails code with ENV['SECRET_KEY_BASE']. Never put secrets in config files or code.

### How do I use a specific Ruby version on Replit?

Set the Ruby version in replit.nix using the appropriate Nix package name. For example, pkgs.ruby_3_2 for Ruby 3.2.x. Check search.nixos.org/packages to find available Ruby version packages for your selected Nix channel.

---

Source: https://www.rapidevelopers.com/replit-tutorial/how-to-manage-ruby-on-rails-dependencies-using-replit-s-package-management-features
© RapidDev — https://www.rapidevelopers.com/replit-tutorial/how-to-manage-ruby-on-rails-dependencies-using-replit-s-package-management-features