Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 36 ยท Vagrantfile and Boxes

Vagrantfile Load Order and Merging

Learn how Vagrant finds and merges several Vagrantfiles: box, user-level and project files, override rules, VAGRANT_VAGRANTFILE and config.vm.define.

So far one Vagrantfile described one machine. In reality, several Vagrantfiles take part every time you run a command, and Vagrant merges them into one final configuration. This explains puzzling behavior ("why is my VM using 512 MB when my file says nothing about memory?") and gives you a clean way to add personal tweaks without touching the team's file. You will learn the order, the merge rules, and how to apply them to your advantage.

The load order

Vagrant gathers configuration from these sources, from lowest to highest priority:

  1. The Vagrantfile packaged inside the box. Box authors set defaults here, such as the SSH username, a default synced folder type or memory size.
  2. The user-level Vagrantfile at ~/.vagrant.d/Vagrantfile. It applies to every project on your computer: perfect for personal preferences.
  3. The project Vagrantfile. Vagrant looks in the current directory and then in every parent directory until it finds a file named Vagrantfile (or the name in VAGRANT_VAGRANTFILE). That is why you can run vagrant ssh from a subfolder.
  4. Multi-machine overrides and provider overrides inside the project file: settings in a config.vm.define block override the top-level ones for that machine, and a provider block applies only when that provider is in use.
flowchart TB
    A["1. Box Vagrantfile (defaults)"] --> M["Merge"]
    B["2. ~/.vagrant.d/Vagrantfile (user)"] --> M
    C["3. Project Vagrantfile"] --> M
    D["4. config.vm.define and provider blocks"] --> M
    M --> F["Final configuration of the machine"]

Later layers win over earlier ones when they set the same value.

Merge rules in practice

For single values the last assignment wins:

Ruby
# ~/.vagrant.d/Vagrantfile  (your personal file)
Vagrant.configure("2") do |config|
  config.vm.provider "virtualbox" do |vb|
    vb.memory = 4096
  end
end

# project Vagrantfile
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"
  config.vm.provider "virtualbox" do |vb|
    vb.memory = 2048
  end
end

The project file is loaded after the user file, so memory ends up as 2048. If you want your own preference to win, it must be applied after the project file, which you can do with an untracked local override file (see below).

For collections, Vagrant appends instead of replacing. Network definitions, synced folders and provisioners accumulate: a base file with one provisioner and a project file with another give a machine with both, running in the order they were loaded. Synced folders are keyed by their guest path, so a later definition of /vagrant replaces the earlier one for that path, and disabled: true removes it.

Overriding for one machine

In a multi-machine file, values set inside config.vm.define apply only to that machine and come after the shared top-level values:

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"      # shared by all machines
  config.vm.provider "virtualbox" do |vb|
    vb.memory = 1024
  end

  config.vm.define "web"
  config.vm.define "db" do |db|
    db.vm.box = "bento/debian-12"            # overrides the box for db only
    db.vm.provider "virtualbox" do |vb|
      vb.memory = 4096                       # overrides memory for db only
    end
  end
end

The web machine uses the shared values; db uses Debian and 4 GB. The Multi-machine chapter of this track expands on this pattern.

A local override file for personal tweaks

A common trick lets each developer keep private settings in a file that is not committed (add it to .gitignore):

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"
  config.vm.provider "virtualbox" do |vb|
    vb.memory = 2048
  end
end

# Load an optional personal file last, so it wins
local = File.join(__dir__, "Vagrantfile.local")
load local if File.exist?(local)

and in Vagrantfile.local (a plain Ruby file with the same structure):

Ruby
Vagrant.configure("2") do |config|
  config.vm.provider "virtualbox" do |vb|
    vb.memory = 8192
  end
end

Because load runs the second Vagrant.configure block after the first, its values override the team defaults. A simpler variant uses a YAML or JSON settings file that the Vagrantfile reads and merges. Either way, the team file stays clean.

Choosing a different file name or location

By default the file is Vagrantfile. Two environment variables change where Vagrant looks:

  • VAGRANT_VAGRANTFILE=Vagrantfile.staging vagrant up uses a different file name in the usual lookup path.
  • VAGRANT_CWD=/path/to/project vagrant status runs Vagrant as if you were in that directory.

This is a convenient way to keep a second environment (for example "ci" or "staging") next to the main one, but remember that .vagrant/ state is per directory, so two files in the same folder share machine IDs unless the machine names differ.

See merging with a stand-in

The following runnable example is a stand-in: a small Ruby function that merges layers the way described above, with scalar values replaced, lists appended, and per-machine overrides on top. It prints which layer each final value came from.

Ruby Layered configuration merge (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.

Notice that provisioners accumulates three entries while memory ends up as the value of the last layer that set it.

Debugging the final configuration

  • vagrant validate loads all layers and reports errors with the file name and line.
  • vagrant ssh-config and vagrant port show the SSH and forwarded-port results of the merge.
  • VAGRANT_LOG=debug vagrant status 2>&1 | grep -i vagrantfile shows which files were loaded.
  • If a value looks wrong, check ~/.vagrant.d/Vagrantfile and the Vagrantfile packaged in the box; both are easy to forget.
  • A packaged box Vagrantfile can be read from the box folder in ~/.vagrant.d/boxes/<name>/<version>/<provider>/Vagrantfile.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which Vagrantfile has the highest priority?

    The order is box, user, project, then machine and provider overrides; later layers win.
  2. 2. What happens to provisioners defined in two layers?

    Collections like provisioners and networks append instead of replace.
  3. 3. How can you let every developer keep personal settings out of the repository?

    A conditional load of a git-ignored file at the end lets personal values override the team file.
  4. 4. Where does Vagrant look for the project Vagrantfile?

    It walks up the directory tree, so subfolders of a project work.

Summary

  • Configuration is merged from the box, your user file, the project file and per-machine or provider blocks; later wins.
  • Scalars are replaced, collections (provisioners, networks) are appended, synced folders are keyed by guest path.
  • A git-ignored Vagrantfile.local loaded at the end gives personal overrides.
  • VAGRANT_VAGRANTFILE and VAGRANT_CWD change which file is used.
  • Use vagrant validate and VAGRANT_LOG=debug to see what was loaded.

Next: Provisioning Overview