How to Run a Ruby Script in Terminal on macOS

You will learn how to open Terminal, move to the folder containing a Ruby file, run it with the ruby command, and diagnose common problems such as an incorrect file path or missing Ruby installation.

A Ruby script is a plain text file containing Ruby instructions, usually saved with the .rb extension. Saving the file does not execute it; Terminal must start the Ruby interpreter and give it the file to read.

The basic relationship is:

ruby file_name.rb

• ruby starts the Ruby interpreter.
• file_name.rb is the script that Ruby should execute.

Terminal runs commands relative to a current working directory. Before running a script by its short name, you usually need to navigate to the directory where that file is stored.

This workflow matters because command-line scripts are commonly used for automation, data processing, developer tools, setup tasks, and testing small programs.

Think of Ruby as a chef and your .rb file as a recipe.

• Writing and saving hello.rb creates the recipe.
• Typing ruby hello.rb gives the recipe to the chef.
• Ruby reads each instruction and produces the result, such as text printed in Terminal.

Terminal is like your current room in a building. If the recipe is in another room, you must either walk there with cd or give the chef the recipe's full address (path).

The standard syntax is:

ruby file_name.rb

For example, create a file named hello.rb:

name = "Ruby"
puts "Hello, #{name}!"

In Terminal, navigate to the folder containing the file and run:

ruby hello.rb

Output:

Hello, Ruby!

Typical macOS Terminal workflow

# Check that Ruby is available
ruby --version

# Move into the folder containing your script
cd ~/Desktop/ruby-practice

# List files in that folder
ls

# Run the script
ruby hello.rb

If ls displays hello.rb, ruby hello.rb should run that file. File names are case-sensitive on many development setups, so hello.rb and Hello.rb should be treated as different names.

Suppose your script is named greeting.rb and contains:

person = "Ada"
puts "Welcome, #{person}!"

Run these commands:

cd ~/Desktop/ruby-practice
ruby greeting.rb

What happens:

1. cd ~/Desktop/ruby-practice changes Terminal's current directory to the ruby-practice folder on your Desktop.
2. ruby greeting.rb starts Ruby and passes greeting.rb as an argument.
3. Ruby reads person = "Ada" and stores the string Ada in the person variable.
4. Ruby evaluates the puts line. #{person} is replaced with Ada.
5. puts prints the result to Terminal:

Welcome, Ada!

To confirm your current directory at any time, run:

pwd

To see the files available there, run:

ls

Running Ruby scripts directly in Terminal is useful for many everyday tasks:

• Automation: Rename files, organize downloads, or generate reports.
• Data processing: Read a CSV file, transform its rows, and write cleaned output.
• API tasks: Fetch data from an API and save a result locally.
• Developer tooling: Run setup scripts, database utilities, linters, or code generators.
• Learning and debugging: Quickly test Ruby syntax and small programs without building a full Rails application.
• Scheduled jobs: Run a Ruby script through cron or another scheduler for recurring work.

In real projects, developers often run Ruby scripts from the project root—the main folder containing the project files.

Run a standalone script

ruby scripts/import_customers.rb

Using a relative path such as scripts/import_customers.rb makes it clear where the script lives.

Pass command-line arguments

A script can receive values after its file name:

ruby greet.rb Sam

# greet.rb
name = ARGV[0] || "Guest"
puts "Hello, #{name}!"

ARGV contains command-line arguments. The || "Guest" part provides a fallback value when no name is supplied.

Validate input with an early exit

# divide.rb
number = ARGV[0]

unless number
  warn "Usage: ruby divide.rb NUMBER"
  exit 1
end

puts 100 / number.to_f

This guard clause stops immediately with a helpful message if required input is missing.

Rails projects

A Rails application has its own commands and environment. Instead of directly running arbitrary application code with ruby, developers often use:

bin/rails console
bin/rails runner 'puts User.count'

For a plain .rb script that does not need Rails, ruby script_name.rb remains the appropriate command.

Running from the wrong folder

If Terminal is not in the folder containing your script, Ruby cannot find it:

ruby hello.rb

Possible error:

ruby: No such file or directory -- hello.rb (LoadError)

Fix it by checking the current folder and its files:

pwd
ls

Then use cd to move to the right directory, or provide the full path:

ruby ~/Desktop/ruby-practice/hello.rb

Omitting the ruby command

Typing only this does not normally execute a script:

hello.rb

Use:

ruby hello.rb

Using the wrong file name or capitalization

If the actual file is Hello.rb, this may fail:

ruby hello.rb

Run ls and copy the name exactly as it appears.

Saving a file with a hidden extra extension

Some editors may save hello.rb.txt instead of hello.rb. Check with:

ls

Rename the file so it ends in exactly .rb.

Confusing a Ruby script with a Rails command

A Rails project uses commands such as bin/rails server and bin/rails console. A standalone Ruby file is usually run with:

ruby file_name.rb

Editing but not saving

Terminal runs the saved version on disk, not the unsaved text currently open in an editor. Save the file before rerunning the command.

irb is useful for experiments, but ruby file.rb is the normal choice when your code has been saved in a script file.

# Verify Ruby is installed
ruby --version

# Show the current directory
pwd

# List files in the current directory
ls

# Move into a folder
cd ~/Desktop/ruby-practice

# Run a Ruby script in the current directory
ruby hello.rb

# Run a Ruby script using a relative path
ruby scripts/hello.rb

# Run a Ruby script using a full path
ruby ~/Desktop/ruby-practice/hello.rb

# Show Ruby syntax errors without running the program
ruby -c hello.rb

# Start an interactive Ruby session
irb

Key rules:

• Save Ruby source files with .rb.
• Use ruby, followed by the script path.
• Use pwd and ls when Ruby cannot find a file.
• Quote paths containing spaces:

ruby "~/Desktop/Ruby Practice/hello.rb"

A more reliable alternative is to change into the folder first, then run the file by name.

How do I run a Ruby file in Terminal?

Navigate to the folder containing the file with cd, then run:

ruby file_name.rb

How can I tell whether Ruby is installed on my Mac?

Run:

ruby --version

If Terminal prints a version number, the ruby command is available.

Why does Ruby say “No such file or directory”?

Terminal is probably in a different directory, or the file name does not match exactly. Run pwd to see your location and ls to see available files.

Do I need to make a .rb file executable?

No. The simplest approach is ruby file.rb, which does not require executable permissions.

Can I run a Ruby file by double-clicking it?

You can configure macOS to do this, but Terminal is better for learning and debugging because it shows output and errors clearly.

How do I stop a Ruby script that keeps running?

Press Control + C in the Terminal window running the script.

How do I check a Ruby script for syntax errors?

Use:

ruby -c file_name.rb

Ruby reports Syntax OK when the file parses successfully.

• Terminal navigation (cd, pwd, ls) — Required to locate files and work with directories from the command line.
• File paths — Explains relative paths, absolute paths, and why commands may not find a script.
• Ruby puts — The standard beginner-friendly way to print output from Ruby programs.
• Ruby variables and string interpolation — Used in basic scripts to store values and build output.
• Command-line arguments (ARGV) — Lets a Ruby script accept input when it is executed.
• Executable files and shebangs — An alternative way to run scripts directly without typing ruby first.
• IRB — Ruby's interactive shell for experimenting with Ruby expressions.
• Rails commands — Helps distinguish standalone Ruby execution from Rails project workflows.