How to Quickly Download and Import Vagrant Boxes from Chinese Mirrors

Preparation

The author tested on macOS Catalina 10.15.3 with Vagrant 2.2.4 and VirtualBox 6.0.15. The guide works for similar environments.

macOS Catalina 10.15.3

Vagrant 2.2.4

VirtualBox 6.0.15

Official Vagrant box downloads often fail in China. Instead, use Tsinghua University mirrors for Ubuntu boxes:

https://mirrors.tuna.tsinghua.edu.cn/ubuntu-cloud-images/vagrant/

Add the boxes with the following commands:

vagrant box add https://mirrors.tuna.tsinghua.edu.cn/ubuntu-cloud-images/bionic/current/bionic-server-cloudimg-amd64-vagrant.box --name ubuntu18

vagrant box add https://mirrors.tuna.tsinghua.edu.cn/ubuntu-cloud-images/xenial/current/xenial-server-cloudimg-amd64-vagrant.box --name ubuntu16

vagrant box add https://mirrors.tuna.tsinghua.edu.cn/ubuntu-cloud-images/vagrant/trusty/current/trusty-server-cloudimg-amd64-vagrant-disk1.box --name ubuntu14

For CentOS, use the official cloud images (may require a VPN):

http://cloud.centos.org/centos/7/vagrant/

http://cloud.centos.org/centos/8/vagrant/

It is recommended to download only the boxes you need and use a multi‑threaded downloader for faster, resumable transfers.

Importing a Box File

Place the downloaded .box file in a local directory and import it with:

vagrant box add ~/Downloads/box/bionic-server-cloudimg-amd64-vagrant.box --name ubuntu/bionic

The box is stored under ~/.vagrant/boxes. Verify the import with: vagrant box list Sample output shows the newly added ubuntu/bionic entry.

Validating the Imported Box

Create a test directory, initialize a Vagrant environment, and bring it up:

mkdir test && cd test
vagrant init ubuntu/bionic
vagrant up

The default Vagrantfile is generated; its content provides a useful reference for configuration options.

# -*- mode: ruby -*-
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/bionic"
  # Additional configuration examples are commented out.
end

After vagrant up, the VM boots with VirtualBox, and you can SSH into it: vagrant ssh The SSH session displays standard Ubuntu system information and confirms the VM is running.

Potential Issues with CentOS 7/8 Boxes

Importing CentOS 7 or 8 boxes may trigger errors during vagrant up. Searching the error codes online usually yields solutions; users are encouraged to seek help if problems persist.

Conclusion

Vagrant is a highly valuable tool for developers in China, forming an essential part of the DevOps toolchain. Accessing reliable box mirrors and manually importing boxes ensures a smoother workflow, and further articles will explore additional Vagrant optimizations and features.