Vagrant difference between package and repackage - vagrant

Question

What is the difference between vagrant box repackage (docs) and vagrant package (docs)?
I realise that vagrant package works only with the VirtualBox provider, but in case only VirtualBox is used - what's the difference? Maybe there's a specific reason vagrant package was created?

Answer 1

vagrant package
If you have a running VirtualBox VM, you created without vagrant first, did your things using VirtualBox, and you now want to use Vagrant to manage this VM. As vagrant needs box to start VM, you will run vagrant package to create a vagrant box based on the existing VirtualBox VM
vagrant repackage
You will use this option when you have an existing vagrant box installed on your system. So you use vagrant with a given box, again you will make change to the VM and you want to save those changes (software installed ...) as a new box, you will run vagrant repackage on this box, and it will create an updated version of this box so it can be used as starting box for new VM.

Answer 2

I will answer with the specific example of the VirtualBox provider on macOS, but this can be generalized to any provider on any host. Although not asked by the op, I will also explain --base NAME because I think it helps in clarifying the difference. I will also use the --output OUTPUT_NAME to distinguish between the packaged boxes.
vagrant package
~/code/vagrant/vm1 > vagrant package --output vm1-package.box
Attempts graceful shutdown of currently running VM which is found from ./.vagrant/... directory
Clears any previously set forwarded ports
Exports the VM (using the provider's export tools) and adds vagrant_private_key
Archives (using tar) everything into ./vm1-package.box
==> vm1: Attempting graceful shutdown of VM...
==> vm1: Clearing any previously set forwarded ports...
==> vm1: Exporting VM...
==> vm1: Compressing package to: /Users/user/code/vagrant/vm1/vm1-package.box
To verify:
~/code/vagrant/vm1 > tar -C /tmp/vm1 -xvf ./vm1-package.box
x ./vagrant_private_key
x ./metadata.json
x ./box.ovf
x ./Vagrantfile
x ./box-disk001.vmdk
Since this packages the currently running VM that Vagrant manages, the above list includes the vagrant_private_key file (which is loaded by the packaged Vagrantfile).
Now, we can add this box to Vagrant's internal storage in ~/.vagrant.d:
~/code/vagrant/vm1 > vagrant box add vm1-package.box --name vm1
==> box: Box file was not detected as metadata. Adding it directly...
==> box: Adding box 'vm1' (v0) for provider:
box: Unpacking necessary files from: file:///Users/user/code/vagrant/vm1/vm1-package.box
==> box: Successfully added box 'vm1' (v0) for 'virtualbox'!
which you can also verify by:
~/code/vagrant/vm1 > ls -lF ~/.vagrant.d/boxes/vm1/0/virtualbox/
total 1152400
-rw-r--r-- 1 user staff 630 13 Dec 16:26 Vagrantfile
-rw-r--r-- 1 user staff 575710720 13 Dec 16:26 box-disk001.vmdk
-rwx------ 1 user staff 6838 13 Dec 16:26 box.ovf*
-rw-r--r-- 1 user staff 25 13 Dec 16:26 metadata.json
-rw------- 1 user staff 1675 13 Dec 16:26 vagrant_private_key
~/code/vagrant/vm1 > vagrant box list
hashicorp/bionic64 (virtualbox, 1.0.282)
vm1 (virtualbox, 0)
vagrant package --base vm_name
~/code/vagrant/vm1 > vagrant package --base vm1 --output vm1-base-package.box
Attempts graceful shutdown of currently running VM which is found from ./.vagrant/... directory
Clears any previously set forwarded ports
Exports the VM (using the provider's export tools) but does not add vagrant_private_key
Archives (using tar) everything into ./vm1-base-package.box
==> vm1: Exporting VM...
==> vm1: Compressing package to: /Users/user/code/vagrant/vm1/vm1-base-package.box
To verify:
~/code/vagrant/vm1 > tar -C /tmp/vm1-base -xvf ./vm1-base-package.box
x ./metadata.json
x ./box.ovf
x ./Vagrantfile
x ./box-disk001.vmdk
Since this packages the currently running VM that Virtualbox manages, the above list does not includes the vagrant_private_key file.
Now, we can add this box to Vagrant's internal storage in ~/.vagrant.d:
~/code/vagrant/vm1 > vagrant box add vm1-base-package.box --name vm1-base
==> box: Box file was not detected as metadata. Adding it directly...
==> box: Adding box 'vm1-base' (v0) for provider:
box: Unpacking necessary files from: file:///Users/user/code/vagrant/vm1/vm1-base-package.box
==> box: Successfully added box 'vm1-base' (v0) for 'virtualbox'!
~/code/vagrant/vm1 > vagrant box list
hashicorp/bionic64 (virtualbox, 1.0.282)
vm1 (virtualbox, 0)
vm1-base (virtualbox, 0)
~/code/vagrant/vm1 > ls -lF *.box
-rw-r--r-- 1 user staff 561848649 13 Dec 16:50 vm1-base-package.box
-rw-r--r-- 1 user staff 561767838 13 Dec 16:19 vm1-package.box
If you delete the box files from the current directory...
~/code/vagrant/vm1 > rm *.box
... you may now use vagrant repackage to get them back:
vagrant box repackage
~/code/vagrant/vm1 > vagrant box repackage vm1 virtualbox 0
This takes the files from Vagrant's internal storage ~/.vagrant.d/... and re-packages them back into a box in the current directory called package.box. In this case, you cannot name the file using the command, so you may want to rename it:
~/code/vagrant/vm1 > mv package.box vm1-package.box
and for the base box:
~/code/vagrant/vm1 > vagrant box repackage vm1-base virtualbox 0
~/code/vagrant/vm1 > mv package.box vm1-base.box
~/code/vagrant/vm1 > ls -lF *.box
-rw-r--r-- 1 user staff 561848571 13 Dec 17:28 vm1-base.box
-rw-r--r-- 1 user staff 561767855 13 Dec 17:24 vm1-package.box
Additional note
The manual is not very clear on the syntax of the vagrant package command with and without the --base option. I think the clarification should be:
vagrant package [options] [vm_name|vm_id]
It should specify that if [vm_name|vm_id] is not specified, then the currently running VM is packaged, otherwirse, the VM specified by [vm_name|vm_id] is packaged.
It should also specify that if you use the --base option, the command should be:
vagrant package --base MANDATORY_NAME [vm_name|id]
but in this case, [vm_name|id] is completely ignored, since the VM has already been specified by MANDATORY_NAME
I verified this by issuing:
vagrant package --base vm1 --output vm1-base-package.box non-existent-vm-name
and it still generated vm1-base-package.box without any errors.