Incluir otros archivos en Ruby: require y load
Ruby hace fácil escribir código modular, así que acabarás con muchos archivos pequeños, cada uno con una parte de la funcionalidad. Para incluir un archivo en otro, Ruby tiene tres instrucciones: require_relative, require y load.
La diferencia principal: require carga cada fichero una sola vez y, si ya está cargado, no lo vuelve a leer; load lo vuelve a ejecutar cada vez que lo pides.
Las tres formas de incluir un archivo
| Instrucción | Dónde busca | ¿Lo carga más de una vez? | Uso típico |
|---|---|---|---|
require_relative "vehiculo" |
Junto al fichero que lo llama | No | Tus propios archivos |
require "json" |
En las rutas de librerías y gemas ($LOAD_PATH) |
No | Librerías y gemas |
load "./vehiculo.rb" |
La ruta que le das, con extensión. Si no empieza por /, ./ o ../, busca en $LOAD_PATH y luego en la carpeta actual |
Sí, cada vez | Recargar código que cambia |
require y require_relative devuelven true la primera vez y false si el fichero ya estaba cargado.
Qué se comparte y qué no
Fichero vehiculo.rb:
gasolina = 2
def total_ruedas
2
end
def que_soy
"eres un vehículo"
end
Fichero ejemplo.rb:
gasolina = 1
total_ruedas = 1
require_relative "vehiculo"
puts "gasolina = #{gasolina}" # gasolina = 1
puts "total ruedas = #{total_ruedas}" # total ruedas = 1
puts "total ruedas() = #{total_ruedas()}" # total ruedas() = 2
puts "qué eres = #{que_soy}" # qué eres = eres un vehículo
gasolinavale 1: las variables locales devehiculo.rbno salen de su fichero.total_ruedasvale 1 porque enejemplo.rbhay una variable local con ese nombre, y la variable gana. Con paréntesis,total_ruedas(), Ruby llama al método del otro fichero y devuelve 2.que_soyfunciona: los métodos definidos en el fichero cargado sí están disponibles.
Los archivos cargados con load o require pueden incluir, a su vez, otros archivos.
require solo carga una vez; load, siempre
# continúa ejemplo.rb, que ya ha cargado vehiculo.rb
p require_relative("vehiculo") # => false: ya estaba cargado
p load("./vehiculo.rb") # => true: load lo vuelve a ejecutar
require se puede ejecutar en cualquier momento
Algo que no es obvio: require es una instrucción normal que se ejecuta cuando llega su turno. Puede ir dentro de un if o recibir un nombre construido en ese momento:
if ENV["MODO"] == "json"
require "json"
puts({ ok: true }.to_json)
end
Este ejemplo escribe un fichero en cada vuelta del bucle y lo carga con load. Como load ejecuta el fichero cada vez, siempre se ve la versión nueva:
3.times do |index|
File.write("generado.rb", <<~RUBY)
module ModuloEjemplo
def self.variable = #{index}
end
RUBY
load "./generado.rb"
puts ModuloEjemplo.variable
end
# 0
# 1
# 2
Con require solo verías el 0: a partir de la segunda vuelta, Ruby considera que el fichero ya está cargado y no lo vuelve a leer.
$LOAD_PATH: dónde busca require
Cuando escribes require "json", Ruby no busca en la carpeta en la que estás. Recorre, en orden, una lista de carpetas que se llama $LOAD_PATH (también $:). Es como la lista de estanterías de una biblioteca: si el libro no está en ninguna, el bibliotecario te dice que no existe, aunque lo tengas en la mochila.
En esa lista están la biblioteca estándar de Ruby y las gemas instaladas, pero no tu proyecto. Hay dos formas de añadir una carpeta tuya:
- Al lanzar Ruby, con
-I. Es lo habitual en los tests:ruby -Ilib test/calculadora_test.rbponelibal principio de la lista. - Desde el código, con
$LOAD_PATH.unshift. Lo verás en scripts sueltos, aunquerequire_relativesuele ser más claro.
Con esta estructura:
lib/calculadora.rb
test/calculadora_test.rb
Fichero lib/calculadora.rb:
module Calculadora
def self.suma(a, b) = a + b
end
Desde la carpeta raíz del proyecto:
ruby -Ilib -e 'puts $LOAD_PATH.first'
/ruta/de/tu/proyecto/lib
Y este script, guardado en la raíz, funciona lo lances desde donde lo lances, porque __dir__ es la carpeta del propio fichero:
$LOAD_PATH.unshift(File.join(__dir__, "lib"))
require "calculadora"
puts Calculadora.suma(2, 3) # 5
Para saber qué se ha cargado ya, Ruby guarda la ruta completa de cada fichero en $LOADED_FEATURES. Es la lista que consulta require para decidir si devuelve false:
require "json"
p require("json") # => false: ya está en $LOADED_FEATURES
p $LOADED_FEATURES.grep(/json\.rb\z/).any? # => true
Errores frecuentes
Los mensajes son de Ruby 4.0.9. Ruby 3.4.12 da los mismos, salvo en los de require: allí la primera línea apunta a rubygems/core_ext/kernel_require.rb, y la de tu fichero sale después, como from err_require.rb:1:in '<main>'.
1. Usar require para un fichero de tu proyecto. require "vehiculo" busca en $LOAD_PATH, y tu carpeta no está:
err_require.rb:1:in 'Kernel#require': cannot load such file -- vehiculo (LoadError)
Usa require_relative "vehiculo".
2. Usar require "./vehiculo" y lanzar el programa desde otra carpeta. ./ es la carpeta desde la que ejecutas ruby, no la del fichero. Desde la carpeta del proyecto funciona; desde la carpeta de arriba (ruby app/err_dot.rb), no:
app/err_dot.rb:1:in 'Kernel#require': cannot load such file -- ./vehiculo (LoadError)
3. Escribir mal el nombre en require_relative. El mensaje te da la ruta completa que ha probado, lo que ayuda a ver la errata:
err_rel.rb:1:in 'Kernel#require_relative': cannot load such file -- /app/vehicul (LoadError)
4. Quitar la extensión en load. require prueba a añadir .rb; load no:
load "vehiculo"
err_load.rb:1:in 'Kernel#load': cannot load such file -- vehiculo (LoadError)
Con extensión (load "vehiculo.rb" o load "./vehiculo.rb") funciona.
5. Esperar que una variable local cruce de fichero. Ya lo has visto en la tabla de qué se comparte, pero el error despista porque no menciona el otro fichero:
require_relative "vehiculo"
puts gasolina
err_local.rb:2:in '<main>': undefined local variable or method 'gasolina' for main (NameError)
Si necesitas compartir un valor, ponlo en una constante (GASOLINA = 2) o, mejor, dentro de un módulo.
Compruébalo con un test
El patrón de lib/ y -I es el que usan los tests de una gema. Fichero test/calculadora_test.rb, con Minitest, que viene con Ruby:
require "minitest/autorun"
require "calculadora"
class CalculadoraTest < Minitest::Test
def test_suma
assert_equal 5, Calculadora.suma(2, 3)
end
end
Desde la raíz del proyecto:
ruby -Ilib test/calculadora_test.rb
1 runs, 1 assertions, 0 failures, 0 errors, 0 skips
Si olvidas el -Ilib, el test ni siquiera arranca:
test/calculadora_test.rb:2:in 'Kernel#require': cannot load such file -- calculadora (LoadError)
Para empezar con tests en Ruby, lee la introducción al testing en Ruby.
Cuándo no usarlos a mano
- En una aplicación Rails, para tus propias clases. Rails las carga por ti con la gema Zeitwerk: en desarrollo, cuando las usas; en producción, todas al arrancar. Su guía marca como «no hacer» los
requirede las clases de la aplicación, como modelos y controladores. - Para pasar datos de un fichero a otro. Las variables locales no viajan, y las globales (
$algo) sí, pero cualquiera puede cambiarlas desde cualquier sitio. Si lo que quieres es leer datos, guárdalos en un fichero de datos y léelos. loadcomo forma normal de cargar código. Cada llamada vuelve a ejecutar el fichero entero y redefine sus métodos y constantes. Resérvalo para recargar a propósito, como en el ejemplo del bucle.
Si constante.rb solo contiene LIMITE = 3 y lo cargas dos veces con load, Ruby avisa de la constante repetida:
load "./constante.rb"
load "./constante.rb"
/app/constante.rb:1: warning: already initialized constant LIMITE
/app/constante.rb:1: warning: previous definition of LIMITE was here
Ejercicio
- Crea
lib/saludo.rbcon un móduloSaludoy un métodoSaludo.hola(nombre). - Escribe
test/saludo_test.rbcon Minitest y lánzalo conruby -Ilib. Quita el-Iliby lee elLoadError. - Cambia el
require "saludo"del test por unrequire_relativeque funcione sin-I. Pista: la ruta es relativa al test, así que sube una carpeta.
Para organizar el código que cargas, usa módulos en Ruby. Y si quieres leer o escribir datos en ficheros, en lugar de cargar código, mira Trabajar con ficheros en Ruby.
Fuentes
- Documentación oficial de Ruby 4.0, Kernel:
requirebusca en$LOAD_PATH, prueba a añadir.rbo.so, devuelvefalsesi el fichero ya está en$LOADED_FEATURESy lanzaLoadErrorsi no lo encuentra;require_relativebusca desde la carpeta del fichero que lo llama;loadnunca pasa las variables locales al fichero que carga. La misma página para Ruby 3.4. - Guía oficial de Rails 8.1 (v8.1.4.1): Autoloading and Reloading Constants.
- Todos los ejemplos se han ejecutado en Docker el 12 de noviembre de 2026 con las imágenes oficiales
ruby:3.4(Ruby 3.4.12, Minitest 5.25.4) yruby:4.0(Ruby 4.0.9, Minitest 6.0.0), con la misma salida en las dos salvo la línea de RubyGems que se indica en los errores. La ruta de$LOAD_PATHse ha sustituido por una genérica. Queloadno añade la extensión se ha comprobado ejecutándolo, igual que el orden de búsqueda deloadcon una ruta relativa (primero$LOAD_PATH, después la carpeta actual). Las salidas de error están recortadas a las líneas que importan. El ejemplo del bucle se ha simplificado respecto al original (de 5 a 3 vueltas, conFile.writeen lugar deFile.openyputslínea a línea).