FileUtils

Added in v1.8 · Updated March 13, 2026 · Modules

ruby stdlib fileutils filesystem io

The FileUtils module provides utilities for manipulating files and directories in Ruby. It’s part of the standard library and offers methods for copying, moving, deleting, and creating files and directories.

Overview

FileUtils simplifies common filesystem operations:

File operations: Copy, move, delete, rename files
Directory operations: Create, remove, navigate directories
Permissions: Change file modes and ownership
Comparison: Compare files and directories

Loading FileUtils

require "fileutils"

For convenience methods without prefix:

include FileUtils

File Operations

Copying Files

require "fileutils"

# Copy a single file
FileUtils.cp("source.txt", "destination.txt")

# Copy multiple files to a directory
FileUtils.cp(["file1.txt", "file2.txt"], "backup/")

# Preserve metadata
FileUtils.cp("source.txt", "destination.txt", preserve: true)

Moving and Renaming

require "fileutils"

# Move a file
FileUtils.mv("old.txt", "new.txt")

# Move files to a directory
FileUtils.mv(["file1.txt", "file2.txt"], "documents/")

# Rename (same as mv within same directory)
FileUtils.mv("old_name.txt", "new_name.txt")

Deleting Files

require "fileutils"

# Remove a single file
FileUtils.rm("file.txt")

# Remove multiple files
FileUtils.rm(["file1.txt", "file2.txt"])

# Remove file if it exists (no error if missing)
FileUtils.rm_f("file.txt")

# Remove all files matching a pattern
FileUtils.rm_rf("*.tmp")

Creating Files

require "fileutils"

# Create an empty file
FileUtils.touch("newfile.txt")

# Update modification time
FileUtils.touch("existing.txt")

# Create multiple files
FileUtils.touch(["file1.txt", "file2.txt"])

Directory Operations

Creating Directories

require "fileutils"

# Create a single directory
FileUtils.mkdir("new_folder")

# Create nested directories
FileUtils.mkdir_p("path/to/nested/folder")

# Create directory with specific mode
FileUtils.mkdir("restricted", mode: 0o750)

Removing Directories

require "fileutils"

# Remove empty directory
FileUtils.rmdir("empty_folder")

# Remove directory and all contents
FileUtils.rm_r("folder/")

# Remove directory if it exists
FileUtils.rm_rf("folder/")

Listing Directory Contents

require "fileutils"

# List files in directory
FileUtils.ls(".")

# List with details (like ls -l)
FileUtils.ls_l(".")

# Recursive listing
FileUtils.ls_r(".")

File Comparison

Comparing Files

require "fileutils"

# Check if files are identical
FileUtils.cmp("file1.txt", "file2.txt")  # => true or false

# Same as cmp
FileUtils.compare_file("file1.txt", "file2.txt")

Comparing Directories

require "fileutils"

# Check if directories have same content
FileUtils.compare_dir("dir1/", "dir2/")

Permissions

Changing Permissions

require "fileutils"

# Change permission mode
FileUtils.chmod(0644, "file.txt")

# Change permissions recursively
FileUtils.chmod_R(0755, "scripts/")

# Change owner
FileUtils.chown("user:group", "file.txt")

# Change owner recursively
FileUtils.chown_R("user:group", "folder/")

Common Permission Patterns

# Make a script executable
FileUtils.chmod(0755, "script.sh")

# Make files read-only
FileUtils.chmod(0444, "readonly/")

# Make files and directories writable
FileUtils.chmod_R(0644, "public/")

Symbolic Links

Working with Symlinks

require "fileutils"

# Create a symbolic link
FileUtils.ln_s("target", "link")

# Create symbolic link (overwrite existing)
FileUtils.ln_sf("target", "link")

# Create hard link
FileUtils.ln("target", "hardlink")

# Remove link
FileUtils.rm("link")

Verbose Mode

Logging Operations

require "fileutils"

# Enable verbose output
FileUtils.verbose do
  FileUtils.cp("source.txt", "dest.txt")
  FileUtils.mkdir("new_folder")
end
# Prints each operation to stdout

Dry Run

Testing Operations

require "fileutils"

# Preview without executing
FileUtils.mkdir_p("new/nested/folder", dryrun: true)
# Prints what would happen but does nothing

Practical Examples

Backup Script

require "fileutils"

def backup_directory(source, destination)
  timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
  backup_name = File.basename(source) + "_" + timestamp
  
  FileUtils.mkdir_p(destination)
  FileUtils.cp_r(source, File.join(destination, backup_name))
  
  puts "Backup created: #{backup_name}"
end

backup_directory("data/", "backups/")

Clean Temporary Files

require "fileutils"

def clean_temp_files(directory)
  Dir.glob(File.join(directory, "*.tmp")).each do |file|
    FileUtils.rm_f(file)
    puts "Removed: #{file}"
  end
end

clean_temp_files("workspace/")

Deploy Application

require "fileutils"

def deploy(source, target)
  # Backup current version
  if File.exist?(target)
    FileUtils.mv(target, "#{target}.bak")
  end
  
  # Copy new version
  FileUtils.cp_r("#{source}/.", target)
  
  # Set permissions
  FileUtils.chmod_R(0755, File.join(target, "bin"))
  FileUtils.chmod_R(0644, File.join(target, "public"))
  
  puts "Deployed successfully!"
end

deploy("build/", "/var/www/app/")

Common Options

These options work across most FileUtils methods:

Option	Description
`force`	Don’t raise error if destination exists
`verbose`	Print operations to stdout
`preserve`	Preserve timestamps and permissions
`noop`	Don’t actually perform the operation
`dryrun`	Same as noop

FileUtils.cp("file.txt", "dest/", force: true, preserve: true, verbose: true)