Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 36 ยท Vagrantfile and Boxes

Vagrantfile Basics

Understand the Vagrantfile: the Ruby DSL, the config object, config.vm settings, variables, loops and conditions, and how to validate your file.

The Vagrantfile is the heart of every Vagrant project. It is a text file named exactly Vagrantfile (no extension), placed at the root of your project. Vagrant searches for it in the current folder and then in each parent folder, so you can run commands from a subdirectory. Although it looks like a configuration format, it is real Ruby code. You do not need to know Ruby to use it, but a little Ruby makes you much more powerful.

The skeleton

Every Vagrantfile has the same outline:

Ruby
Vagrant.configure("2") do |config|
  # settings go here
end

Vagrant.configure("2") starts configuration version 2 (the one used by all current Vagrant releases). It takes a block: the code between do and end. Vagrant passes your block an object named config, and everything you write sets properties on that object. The name config is only a convention; you could call it anything.

Settings are grouped into namespaces under config:

Namespace Controls
config.vm The machine: box, network, synced folders, provisioners, hostname
config.ssh How Vagrant connects: username, keys, forwarding the agent
config.vagrant Vagrant's own behavior, e.g. sensitive values
config.trigger Actions before or after commands
config.env Environment settings of the Vagrant process

A realistic example

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"
  config.vm.hostname = "dev"
  config.vm.box_check_update = false

  config.vm.network "forwarded_port", guest: 3000, host: 3000
  config.vm.synced_folder ".", "/vagrant", disabled: true
  config.vm.synced_folder "./app", "/srv/app"

  config.vm.provider "virtualbox" do |vb|
    vb.memory = 2048
    vb.cpus = 2
  end

  config.vm.provision "shell", inline: <<~SHELL
    apt-get update
    apt-get install -y git
  SHELL
end

Each line is a Ruby method call. config.vm.box = "..." assigns a value; config.vm.network "forwarded_port", guest: 3000, host: 3000 calls a method with a string and keyword arguments (the guest: and host: parts). A do |vb| ... end block configures the provider. The <<~SHELL ... SHELL is a heredoc, a multi-line string whose indentation is trimmed.

Ruby lets you drop parentheses, so config.vm.network "forwarded_port", guest: 80, host: 8080 is the same as config.vm.network("forwarded_port", guest: 80, host: 8080). Both styles appear in documentation.

Using Ruby: variables, loops, conditions

Because the file is Ruby, you can remove repetition and adapt to the environment:

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"

  # a constant, easy to change in one place
  app_ports = [3000, 5432, 6379]

  app_ports.each do |port|
    config.vm.network "forwarded_port", guest: port, host: port + 10000
  end

  # a condition on the host operating system
  if Vagrant::Util::Platform.windows?
    config.vm.synced_folder ".", "/vagrant", type: "smb"
  end

  # an environment variable with a default
  memory = ENV.fetch("VM_MEMORY", "2048").to_i
  config.vm.provider "virtualbox" do |vb|
    vb.memory = memory
  end
end

Environment variables are a good way to let people tune a machine without editing the file: VM_MEMORY=4096 vagrant up. Be aware that settings applied by up stay until you reload. You can also read files (File.read, JSON or YAML configuration) to drive the setup from a data file, a pattern the Multi-machine chapter builds on.

See the DSL idea in action

The stand-in below reproduces the two key tricks of the Vagrantfile: a block that receives a config object, and nested namespaces (config.vm.box). It records every call and then prints the configuration, including values produced by a loop. It is not the real Vagrant, just the same Ruby mechanics.

Ruby Namespaces and loops in a Vagrantfile (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Real Vagrant works along the same lines: each namespace collects the settings, and nothing is applied until a command such as vagrant up runs. That is why a Vagrantfile is evaluated top to bottom first and then validated.

Validate and debug

Run vagrant validate to evaluate the file and get an error message with a line number if it has a syntax or configuration error:

CONSOLE
$ vagrant validate
Vagrantfile validated successfully.

Typical mistakes:

  • A missing end: Ruby reports syntax error, unexpected end-of-input. Indent consistently to spot it.
  • Using curly quotes copied from a web page: replace them with straight " quotes.
  • Calling a setting that does not exist: config.vm.memory = 2048 is wrong; memory belongs in the provider block.
  • Forgetting that the file runs every time: code like puts "hello" at the top prints on every command. Use it only for debugging.

You can also print the effective configuration of a machine with vagrant ssh-config, vagrant port, or inspect problems with VAGRANT_LOG=debug vagrant up.

Style tips

  • Keep the Vagrantfile small and move shell logic into script files (see Shell provisioner).
  • Pin the box version for team projects (see Choosing a box).
  • Comment why, not what: # 4 GB because the build needs it.
  • Commit the Vagrantfile; ignore .vagrant/.
  • Fail early with Vagrant.require_version ">= 2.3.0" at the top of the file.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In which language is a Vagrantfile written?

    The Vagrantfile is Ruby code that uses a configuration DSL, so loops, variables and conditions all work.
  2. 2. What does Vagrant.configure("2") do?

    "2" is the configuration syntax version; the block receives the config object you set properties on.
  3. 3. Where do memory and CPU settings belong?

    Hardware settings are provider specific, so they live inside a provider block.
  4. 4. Which command checks the Vagrantfile without starting a VM?

    vagrant validate evaluates the file and reports syntax and configuration errors.

Summary

  • The Vagrantfile is Ruby, wrapped in Vagrant.configure("2") do |config| ... end.
  • Settings live in namespaces such as config.vm and config.ssh; provider settings sit in a provider block.
  • Ruby features (variables, loops, ENV, if) make one file adapt to many situations.
  • vagrant validate catches errors early; keep the file small and commented.

Next: Choosing a Box