vagrant-parallels: running Vagrant boxes on Parallels Desktop for Mac

A provider, not a hypervisor

The Vagrant Parallels Provider is a plugin for Vagrant, allowing to manage Parallels Desktop virtual machines on macOS hosts.

That framing is worth being clear about, because Vagrant's architecture has two halves and this project is only one of them. Vagrant itself is the tool that takes a `Vagrantfile`, works out what machine you asked for, and drives a provider to create it. The provider is the adapter that knows how to talk to one specific hypervisor. Vagrant ships with providers for VirtualBox and Docker, and this repository adds one for Parallels Desktop.

The practical consequence is that a Parallels-backed Vagrant workflow still depends on a box, a packaged base image, and the provider needs a box built for Parallels. A VirtualBox box will not boot here, and the provider's own documentation has a Boxes section for that reason.

The intended user is a macOS developer who has Parallels Desktop installed and wants their disposable development environments to be Parallels guests. That is a specific and reasonable group: on macOS, VirtualBox performance and integration are perennial complaints, and running the guest under the same hypervisor as the rest of the desktop has its own appeal.

The primary language is Ruby, the licence is MIT, the default branch is `master`, and the last push was on 2026-09-07 with the repository not archived. The recent releases are v2.4.7 from 2025-06-26, v2.4.6 from 2025-06-19 and v2.4.5 from 2025-03-11. The homepage is at parallels.github.io/vagrant-parallels.

The edition restriction is the first thing to check

There is a note in the README that decides the question for a lot of people before they get to any configuration.

Only Pro, Business and Enterprise editions of Parallels Desktop for Mac are compatible with this Vagrant provider. The reason given is short and specific: the Standard edition doesn't have a full command line functionality and can not be used with Vagrant.

That is worth understanding rather than treating as a licensing footnote. A Vagrant provider is a command line client. It shells out to the hypervisor's tools to create a machine, start it, import an appliance, read its network configuration and shut it down. Without a complete `prlctl` and the rest of the command line surface, there is nothing for the provider to talk to. The requirement is functional, not contractual, and the version floor of Parallels Desktop 11 for Mac follows from the same dependency.

The other stated requirement is Vagrant v1.9.7 or higher, which is a floor rather than a current version, so the plugin is written against a broad range of Vagrant releases.

Together with the macOS host requirement, the supported configuration is narrow: a Mac, a paid tier of Parallels Desktop, and Vagrant. That is not a criticism of the project, it is the nature of the integration, but it does mean the plugin is a choice with a precondition rather than a drop-in for everyone who has a Mac.

The installation section repeats the expectation that you already have Parallels Desktop for Mac and Vagrant properly installed, and recommends the latest versions of both.

Installing the plugin

Installation has a build-tool step that catches people out, because Vagrant plugins are Ruby gems and the gem has a native component.

The first step is the command line software development tools provided as a part of Xcode, and the README gives the command:

xcode-select --install

Without those tools, the plugin cannot be built on your machine, and the failure appears at plugin install time rather than at Vagrant run time.

The second step installs the plugin into Vagrant itself:

vagrant plugin install vagrant-parallels

That is a plugin install rather than a gem install, because Vagrant manages its own plugin set and loads the provider only when a `Vagrantfile` asks for it. The practical effect is that the provider is available as a first class provider, so a `Vagrantfile` with the Parallels provider configured in it will pick it up, and a Vagrantfile configured for another provider is unaffected.

The documentation then points at three pages, and the choice of those three is a useful signal about what a new user needs. The Usage page, the Getting Started page and the Boxes index. Boxes come first among the practical concerns because a provider is only useful with a box that matches it.

Bugs and issues go to the issue tracker on GitHub, and the README's contributors section names Youssef Shahin and Mikhail Zholobov as authors, with the copyright line reading 2013-2023, Parallels International GmbH. The MIT licence, with the `LICENSE.txt` file at the root, is the whole of the licensing arrangement, and for a plugin that talks to a commercial hypervisor through its command line interface, that is the expected shape: the plugin itself is open, the product it drives is not.

What the provider covers, and what the docs do not

The features section is a single sentence, and it is worth reading as a scope statement rather than a boast: the Parallels provider supports all basic Vagrant features, including Shared Folders, Private and Public Networking, Forwarded ports and Vagrant Share.

Those four map onto the parts of a Vagrant workflow people actually depend on. Shared folders are how the guest sees your project directory, and they are the reason many people move to Vagrant at all. Private networking covers the host-only adapter case, public networking covers the NAT or bridged case where the guest needs to be reachable, and forwarded ports cover the `config.vm.network` case that predates the other two.

What is not listed is as informative. There is no mention of snapshots beyond what the basic feature set implies, no mention of synced folders as a distinct concept, no mention of box formats other than what the Boxes documentation covers, and no mention of any provider-specific configuration surface. That is a reasonable place for a provider to be for most use cases, but it does mean the provider documentation pages are where the detail lives rather than the README.

The README also makes a recommendation to newcomers: if you're just getting started with Vagrant, it is highly recommended that you read the official Vagrant documentation first. That is an unusual thing for a provider README to say, and it reflects the shape of the project. The provider is thin by design, sitting underneath Vagrant rather than replacing it, so the knowledge that matters is mostly Vagrant knowledge plus a small Parallels-specific surface.

The provider documentation is hosted at parallels.github.io/vagrant-parallels/docs/, and the repository carries a `website/` directory that is the source of that site, along with a `locales/` directory, which tells you the provider's user-facing strings are translated.

The repository layout of a Vagrant provider

The tree is a small Ruby project with the structure of a Vagrant plugin, and reading it tells you how the pieces fit.

`lib/` holds the provider implementation, `locales/` holds the translated strings, `tasks/` holds the Rake tasks, `test/` holds the test suite, and `website/` is the source of the documentation site. The packaging is `vagrant-parallels.gemspec` with a `Gemfile` and a `Rakefile`, and the `vagrant-spec.config.example.rb` is a configuration example for the `vagrant-spec` test harness, which is how Vagrant providers are conventionally tested against a matrix of scenarios.

The `CHANGELOG.md` and `CONTRIBUTING.md` files are both present, and the badges in the README header tell you about the checks: a Gem version badge for the published gem, a Travis CI build status badge on the `master` branch, and a Code Climate badge for the quality score. The presence of Travis in a 2026 project is itself a small historical note, since that service was retired, so the badge reflects the build status at the time the configuration was last valid rather than a live signal.

The `CHANGELOG.md` is the file to read before upgrading. For a provider, the changelog matters more than usual, because a provider change can alter how an existing `Vagrantfile` behaves, and a change to how shared folders or networking are wired up is exactly the kind of thing that breaks a working setup silently.

Maintenance state, and where the plugin is the wrong answer

The version picture is the one thing to weigh. v2.4.7 was published on 2025-06-26, v2.4.6 on 2025-06-19 and v2.4.5 on 2025-03-11, and the last push to `master` was on 2026-09-07. The repository is not archived.

So the tree is receiving work and the tags are sparse, with a cluster of patch releases in June 2025 and a gap of more than a year to the most recent push. For a provider whose job is to track a commercial product's command line interface, that gap is the thing to check, because Parallels Desktop ships its own updates and the provider has to keep up with the `prlctl` surface it drives. The README does not document a supported version matrix for Parallels Desktop, so the check is empirical: install the plugin on the Parallels version you actually have, and run the simplest box in the catalogue before you rely on it.

With that in place, there are three cases where this plugin is the wrong answer.

The first is the Standard edition of Parallels Desktop, which the README rules out explicitly, and there is no workaround at the provider level.

The second is a non-macOS host. The provider drives Parallels Desktop, which is a macOS product, so this is a plugin for Macs and nothing else. On Linux or Windows, the VirtualBox or Hyper-V providers are the ones that apply.

The third is a team that has standardised on VirtualBox. Vagrant's provider layer is exactly the abstraction that makes that choice swappable, and a provider per hypervisor means a `Vagrantfile` that names one is coupled to it. If your organisation has boxes built for VirtualBox, a standard for tooling that already exists, the OpenSSH connection and the synced folder behaviour everyone knows, then this plugin adds a new box catalogue and a new set of behaviours to learn for a benefit that is a matter of preference rather than necessity.

The alternative approach, for comparison, is to drive Parallels directly with its own command line tooling and a small script of your own. The difference in approach is that the provider gives you Vagrant's lifecycle, its `vagrant up`, `vagrant ssh`, `vagrant destroy` and its box format, while a script gives you full control over what Parallels does and none of Vagrant's conveniences in return. For a developer who already lives in Vagrant, the provider is the smaller jump.

Editorial conclusion

Adopt vagrant-parallels if your team develops on macOS, you use Vagrant, and you want the virtual machines to be Parallels Desktop guests rather than a second hypervisor, since the provider supports the basic Vagrant feature set and installs as a plugin. Do not adopt it if you hold the Standard edition of Parallels Desktop, since the README rules it out, or if you are on a Linux or Windows host. Verify three things first: that your Parallels Desktop edition is one of the three that ship the command line interface, that the Vagrant version on the machine is 1.9.7 or newer, and that the base box you intend to use is listed in the provider's boxes documentation, because Vagrant providers each carry their own box catalogue and a box built for another provider will not boot here.

Frequently asked questions

Official sources

1. License: MIT
2. Parallels/vagrant-parallels on GitHub
3. Project website
4. README
5. Releases