Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This guide contains information about all functions of Parallels Desktop for Macs that are or can be related to software development and testing.
The Parallels plugin for Visual Studio allows you to develop software in one virtual machine and test it in other virtual machines with just one click.
Warning: This functionality will be deprecated in Parallels Desktop 20.
To use this plugin, you need the following:
A Windows 7 (or later) virtual machine with Visual Studio Professional/Enterprise 2013 (or later).
Other running virtual machines (with Windows 7 or later) in which you will test the project.
The virtual machine with Visual Studio and other virtual machines must belong to the same pool of IP addresses or just be configured to use the shared network.
All virtual machines must have Parallels Tools installed.
The virtual machine with Visual Studio must have the Access Windows folders from Mac option selected.
Other virtual machines must have the Share Folders: All disks option selected.
The user accounts logged in to the virtual machines in which you're going to test your project must have both username and password, and you must know them.
To install the Parallels plugin, do the following:
In the virtual machine with Visual Studio, navigate to the directory where Parallels Tools are installed. For both Intel and Apple Silicon Macs, it is C:\Application Files\Parallels\Parallels Tools\DevTools
.
Double-click the VMDebugHelper(*version number*).vsix file. The plugin for Visual Studio will be installed automatically.
To start remote debugging of your project, follow these steps:
In the virtual machine where Visual Studio is installed, open Visual Studio and open your project.
Build the project and test it locally.
Click PARALLELS > Start Debugging in VM and select the virtual machine you need (this virtual machine must be running).
Your project will open in the selected virtual machine.
Recognizing the diverse needs of software developers, we've crafted a comprehensive toolkit combining powerful plugins, widely-used resources like Packer and Vagrant, and tools designed specifically for an optimal developer experience. Our open-source initiatives, from Visual Studio Code extensions to DevOps instruments, are provided free of charge. We want to foster a collaborative community by making our source code accessible on GitHub and offering a Discord server for peer support and contribution. We believe that collective effort and shared knowledge will help improve both our product and your workflow.
Note: This manual covers using Parallels Desktop Pro and Business Editions unless explicitly stated otherwise.
When you start a virtual machine operating in the shared or host-only networking mode, and it gets an IP address assigned via DHCP, the virtual machine gets registered in the macOS etc/hosts file, and you can use its name to connect from the host operating system or other virtual machines operating in the shared or host-only networking mode.
For example, after starting such a virtual machine, your etc/hosts file may look as follows:
You can use the virtual machine name (windows-11.shared) to connect to this virtual machine. For example, if you execute the following command in the macOS Terminal:
, you will start pinging 10.211.55.3.
When such a virtual machine is shut down, its registration entry is removed from the etc/hosts file.
If you're working with a virtual machine in the Window or Full-Screen view mode, you can easily and quickly change the virtual machine screen resolution. Simply click the View menu in the macOS menu bar, point to Set Resolution, and choose the screen resolution you need.
Note: Set Resolution requires virtual machines with Parallels Tools installed. The Show developer tools option must be enabled in the More Options pane of the virtual machine configuration.
If you're working with the virtual machine in Full Screen on multiple displays, the screen resolution is changed on the display where you selected a new resolution.
For those beginning their path as developers of AI software, Parallels offers a pre-configured Linux-based virtual machine jam-packed with a diverse collection of third-party tools, and code examples to help you integrate third-party AI models into your projects.
This comprehensive toolkit for computer vision, scientific computing, machine learning, audio processing, image processing, and more equips you to build, analyze, and innovate across a broad spectrum of AI-driven applications.
A dedicated, isolated virtual machine is a safe way to start playing and learning, without dealing with an error-prone setup involving dependencies directly on your Mac. Our prepackaged VM is ready to use and when you are done, you can remove the machine, leaving your main macOS system as clean as it was previously.
Note: This machine is only available to those with current Parallels Desktop for Mac Pro, Business, or Enterprise licenses.
This section contains some specific information on how you can best start your AI development journey using our tools.
Parallels provides a Visual Studio Code extension that can help you manage a wide range of operations for your Parallels Desktop virtual machines, creating, grouping, operating their snapshots and containers. It is integrated with HashiCorp Vagrant and Packer to automate your workflows.
To install the extension:
Launch Visual Studio Code;
Use Shift+Command+X to launch the extension section;
Use the search box to find "Parallels Desktop
" and install the extension.
Learn how to make the most use of the extension by reading the detailed guide here.
Starting from Parallels Desktop 19, users of Pro and Business editions can run x86-64 binaries in Linux virtual machines on Mac computers powered by Apple Silicon. One of the most obvious benefits of this is the ability to run x86 Docker containers in Linux virtual machines.
Note: This functionality is powered by Apple's Rosetta code translation layer that allows running x86-64 code on Apple Silicon processors. It requires macOS Ventura 13 or newer as the host operating system. Known limitations include a lack of support for Snap Packages, potential cross-architecture dependency issues, and incomplete support for Red Hat/RHEL-based distributions.
To speed up the process, Parallels offers a ready-to-download, preconfigured Ubuntu 22.04.02 virtual machine with Rosetta set up, dependencies updated, and Docker ready to go.
To install it, open Control Center in Parallels Desktop > create a new virtual machine from the list of Free Systems and select Download Ubuntu with x86_64 emulation > click Continue to create and start the virtual machine.
You can now start using Docker in the Terminal immediately to create x86-64 containers, as the Docker command-line interface (CLI) is pre-installed in the appliance, or try installing software, provided it conforms to the limitations.
Note: For manual setup instructions and various troubleshooting scenarios, please refer to our KB article.
When creating a virtual machine in Parallels Desktop Pro or Business Edition, the setup process includes a page where you can choose the primary use case, like software development or software testing.
However, you can later change the optimization profile of an already existing virtual machine by doing the following:
Start Parallels Desktop.
In Control Center, right-click the virtual machine (it must be shut down) and choose Configure.
On the General tab, click Change.
Select the profile that best fits your needs.
In software development, it may be beneficial to simulate various network conditions (low speeds, high packet loss, etc.) to see how your app behaves and eliminate potential sources of complaints. Parallels Desktop allows you to do just that by applying machine-specific connection profiles that mimic popular scenarios. To choose from a variety of preset options, do the following:
In Parallels Desktop Control Center, right-click on the required virtual machine and choose Configure.
Switch to the Hardware tab and choose Network from the list on the left.
Use the Profile drop-down menu to select one of the preset scenarios.
Alternatively, click on Configure to manually adjust speeds, pings, and packet loss percentages as required.
Our pre-configured AI development machine comes free of charge and is easy to install:
Open Visual Studio Code and click on Extensions in the left bar, or use the Shift-Command-X shortcut;
Search for Parallels Desktop and install the extension, or use this direct link;
Switch to the Parallels Desktop extension in the left bar and use the Parallels Catalog section to download the pre-configured virtual machine using the Download button;
Agree to download and install the Parallels DevOps service if prompted;
Choose the name and location for your new virtual machine in the top field and confirm with Enter;
Wait for the machine to download;
Once the virtual machine downloads and launches, follow its prompt to set up a new password, install Parallels Tools, and reboot;
Once rebooted, the virtual machine will launch a dedicated AI Developer Package app where you can download ML models and read the documentation.
Both Arm and x86 versions support establishing a Serial port connection over TCP. Ports open on the host machine and do not depend on the guest VM's network settings.
Note: You can find more information about setting up a Serial port on a Parallels VM in the respective section of this guide.
Serial over TCP can be used for remote debugging of VMs. You will need to set up your VM as a Server if you want to debug it or as a Client if you want to use it to debug other machines. Begin by choosing New Socket from the Source drop-down menu and type in tcp://0.0.0.0:2020 for the Server role or tcp://127.0.0.1:2020 for the Client role. Use the Mode drop-down menu to choose the appropriate role. IPv6 is also supported, so you can set up the Server as tcp://[::]:2020 and the Client as tcp://[fe80::1023:163b:ef12:d40e%eth0]:2020.
Nested virtualization implies running a virtual machine inside of another virtual machine.
Note: This functionality is only available on Intel Macs, provided that the host virtual machine is configured to use the Parallels Hypervisor.
To toggle between the Apple's and Parallels's hypervisors, do the following:
Open Parallels Desktop, right-click on the required virtual machine and choose Configure.
Switch to the Hardware tab and choose CPU & Memory from the list on the left.
Click Advanced, and use the Hypervisor drop-down menu to choose Parallels.
Check the Enable nested virtualization box.
Click OK.
When enabled, this functionality allows you to run:
Hyper-V virtual machines inside Windows 8, Windows 10, and Windows Server 2012 virtual machines;
VMware ESXi virtual machines;
Xen and kernel-based virtual machines in versions of Linux that support Xen and KVM.
Note: Nested virtualization may dramatically reduce the performance of both host macOS and virtual machines.
If you use Parallels virtual machines to build, debug, and test applications, enable nested virtualization to install and work in:
Android emulator for Visual Studio;
iPhone emulator for Visual Studio;
Xamarin.Android;
Android Studio;
Embarcadero RAD Studio;
Docker for Windows;
Microsoft Visual Studio + TwinCat 3 (support for TwinCat 3 is being tested, and there may be some bugs).
If you need to generate the virtual machine memory dump, you can do this from Parallels Desktop. When the virtual machine is running, click the Develop menu in the macOS menu bar and choose Generate Core Dump. For more details on where the dump is stored and how to convert it to the Linux, Windows, or macOS format, please refer to the prlcore2dmp topic .
When a virtual machine operating in the shared networking mode sends a DNS request, the request is now resolved also using the macOS etc/hosts file.
For example, if your macOS etc/hosts file contains the following entry:
and you start pinging testh in a virtual machine, the guest OS will check the macOS etc/hosts file first and start pinging 1.2.3.5.
If you don't have enough time to create a new virtual machine with the required configuration, you can download a ready-to-use virtual machine with a predefined configuration.
Parallels Free Systems are pre-built virtual machines with a variety of operating systems (Linux, Windows, Android).
To download such a system and use it with Parallels Desktop:
Choose File > New.
Select the system you need in the Free Systems section, click Continue, and follow the onscreen instructions.
Once the download is complete, you can start working with this system in Parallels Desktop.
Parallels Desktop DevOps Service enables you to manage and orchestrate multiple Parallels Desktop hosts and virtual machines. It will allow you to create, start, stop and delete virtual machines and will also allow you to manage the hosts that are running the virtual machines.
You can use the service for free with up to 10 users, without needing any Parallels Desktop Business or Enterprise Edition license. However, if you want to continue using the service beyond 10 users, you will need to purchase a Parallels Desktop Business or Enterprise license.
However, if you already have a Parallels Desktop for Mac Business or Enterprise Edition license, the DevOps service does not cost you extra.
The Parallels Desktop DevOps is a service that is written in Go and designed to provide some of the missing remote management tools for virtual machines running remotely in Parallels Desktop. It uses Rest API to execute the necessary steps. It also has RBAC (Role Based Access Control) to allow for a secure way of managing virtual machines. You can manage most of the operations for a Virtual Machine Lifecycle.
To install and configure the DevOps service, follow the dedicated guide here.
The prlsrvctl command-line utility is used to perform management tasks on Parallels Desktop. The tasks include getting the Parallels Desktop information, modifying Parallels Desktop preferences, installing a license, obtaining statistics and problem reports, and others.
The general syntax is as follows:
prlsrvctl command [options] [-v, --verbose number]
The parameters are:
command: one of the available commands.
options: command options.
-v, --verbose number: Show verbose output. The greater the number, the more verbose output will be produced.
The subsequent sections describe the available prlsrvctl commands grouped by functionality.
The dedicated Ubuntu virtual machine from Parallels contains documentation and code snippets that can get your AI software development workflow going in no time, giving useful, actionable examples in computer vision, text analysis, etc.
Find them by launching the preinstalled Parallels Desktop AI Development Package app and clicking on the Documentation button.
Before you proceed with any experiments, make sure you use the Download Models section to download the latest available models.
Parallels Desktop 19 and newer features integration with HashiCorp Packer, where their Parallels Packer builder is now able to create Parallels Desktop virtual machines from ISO images, add and provision software of your choice, and export them in the PVM format. The resulting directory contains all the files required to run the virtual machine portably.
You can find more guides and examples on this .
prlsrvctl info
Displays the detailed information about the Parallels Desktop configuration.
Optional parameters
--license
If included, only the Parallels Desktop license information is displayed.
--activation-id
If included, only the license activation ID is displayed.
--deactivation-id
If included, only the license deactivation ID is displayed.
--json
Produces the machine-readable output in JSON format.
If you're using Chef to provision your Parallels virtual machines or host systems running Parallels Desktop, you can check in the recipe that the type of system virtualization being used is virtualization from Parallels. To do this, use the node['virtualization'] attribute. This attribute is set by Ohai during the chef-client run.
Note: The Ohai version must be 8.6.0 or later.
You will see the following in the host system:
And the following in the guest system:
You can build and distribute your portable development environments based on Parallels Desktop for Mac using the officially supported Parallels provider which is available for free from here.
Once you have the latest versions of Parallels Desktop for Mac and Vagrant installed, use this command to install the integration plugin:
You can set up your Vagrant-managed virtual machine by following this guide.
prlsrvctl update-license
Updates the current Parallels Desktop license.
prlsrvctl deferred-license <--install | --remove>
Installs or removes a license stored for deferred installation.
Parameters
--install
Installs the license stored for deferred installation.
--remove
Removes the license stored for deferred installation.
prlsrvctl deactivate-license [--skip-network-errors]
Deactivates the current Parallels Desktop license. The --skip-network-errors option skips network errors and removes the license locally.
In Pro and Business Editions, you can control Parallels Desktop and virtual machines from the command-line interface. Our CLI utilities support the majority of the functions available via the graphical user interface.
Note: This section of the guide covers all supported types of virtual machines (Windows, Linux, and Mac), unless explicitly stated otherwise.
The command-line interface includes the following utilities:
prlsrvctl — the utility is used to manage Parallels Desktop. The tasks include getting general information about Parallels Desktop, modifying Parallels Desktop preferences, getting a list of users, obtaining statistics, installing a license, and others.
prlctl — the utility is used to manage virtual machines. The tasks include creating and configuring virtual machines, snapshot management, cloning operations, installing Parallels Tools, obtaining statistics, generating problem reports, and many others.
The command-line utilities are installed on a Mac as part of Parallels Desktop installation. You can run the utilities in Terminal.
Note that to get help about a particular command, you can type man <name_of_the_command>
in Terminal. This will list the command attributes and additional help.
prlsrvctl set
The prlsrvctl set command is used to modify Parallels Desktop preferences. The available parameters and options are described below.
--mem-limit <auto | size>
Sets the total memory allocated to Parallels Desktop and its virtual machines. The auto option optimizes memory usage. The size option allows the user to set the memory size manually.
-s, --min-security-level <low | normal | high>
Specifies the minimum connection security level to connect to the server. Low - no transmitted data is encrypted. Normal - only the most important data is encrypted. High - all transmitted data is encrypted.
-c, --cep <on | off>
Enables or disables participation in the Customer Experience Program.
--verbose-log <on | off>
Enables or disables verbose logging.
--log-rotation <on | off>
Enables or disables automatic rotation of the Parallels Dispatcher Service and virtual machine log files.
--allow-to-confirm [--host-admin <name>]
Forces the prompt to enter admin credentials or a custom password if an operation requires it. If no operation requires a password, this option will be ignored. If an operation requires a password but this option is omitted, the operation will fail with a corresponding error.
To make an operation require a password, use the following options: --require-pwd, --require-custom-pwd, or --lock-edit-settings, as described below.
The [--host-admin <name>] option specifies the host administrator name if an administrator password is required to unlock the Parallels Desktop preferences for editing.
--allow-attach-screenshots <on | off>
Enables or disables attaching virtual machine and host screenshots to a problem report.
--require-pwd <create-vm | add-vm | remove-vm | clone-vm>:<on | off>
Require entering an administrator password to perform a corresponding action (create a VM, add a VM, etc.). Use --allow-to-confirm to make the system ask for username and password.
--require-custom-pwd <create-vm | add-vm | remove-vm | clone-vm | edit-preferences>:<on | off>
Require entering a custom password to perform a corresponding action. Use --allow-to-confirm to make the system ask for username and password. Other options are self-explanatory.
--custom-pwd [--custom-pwd-mode <on | off | change>] [--replace-commands]
Set, reset, or change the custom password for operations that require it. See the explanation of the parameters below.
--custom-pwd-mode <on | off | change> — set, reset, or change the custom password for operations which require it.
--replace-commands — specify this option to reset commands that are protected with the admin password. This means that when you enable a custom password, commands that require the admin password will now require a custom password. Commands that previously required a custom password will be discarded. The same logic is used when you switch back to the admin password (set --custom-pwd-mode to off). When you disable a custom password, commands that require it will now require the admin password. Commands that previously required the admin password will be discarded. This option is ignored if --custom-pwd-mode is set to change.
--lock-edit-settings <on | off [--host-admin <name>]>
Locks or unlocks Parallels Desktop preferences for editing. The --host-admin parameter specifies the host administrator name if an administrator password is required to unlock Parallels Desktop preferences for editing.
--external-dev-auto-connect <host | guest | ask>
When a new external device is attached to the Mac, connect it to the host, or guest, or ask the user what to do.
--hide-license-request-params <on | off>
Hides the host name and username in requests to Parallels Licensing Server.
This section describes Parallels Desktop license management tasks.
prlsrvctl install-license <-k, --key <key>>
Installs a Parallels Desktop license. The -k, --key <key> parameter specifies a Parallels Desktop license key to install.
Optional parameters
-n, --name <name>
The license owner name.
-c, --company <name>
The license company name.
--deferred
Stores the license for deferred installation. The license will be activated the next time Parallels Desktop is started. If a license has already been activated, it should be deactivated first before using this option. See the prlsrvctl deactivate-license command.
--activate-online-immediately
Activates the license over the Internet immediately.
Note: When activating Parallels Desktop Pro or Standard editions, you must be signed in to your Parallels account before executing this command. See Sign into Parallels Account.
This section includes information on various integrations that improve your development-related workflows that involve running virtual machines on Parallels Desktop for Mac.
prlsrvctl user list [-o, --output field [,field...]] [-j, --json]
Lists users currently existing in Parallels Desktop. The -o, --output field [,field...] option is used to display the specified field(s) only.
prlsrvctl user set <--def-vm-home <path>>
Modifies the default virtual machine's location to the specified path.
prlsrvctl net info <vnetwork_id>
Displays a detailed information about the specified virtual network.
prlsrvctl net list [-j, --json]
Lists existing virtual networks.
prlsrvctl net set <vnetwork_id> [options]
The prlsrvctl net set command is used to modify virtual network settings. The available parameters and options are described below.
Parameters
-i, --ifname <if>
Sets the name of the network interface in Parallels Desktop to which the virtual network will be bound.
-m, --mac <mac>
Sets the MAC address of the network interface in Parallels Desktop to which the virtual network will be bound. The network interface with the specified MAC address must exist in Parallels Desktop.
-t, --type <bridged | host-only | shared>
Sets the virtual network type.
-d, --description <description>
Sets the virtual network description.
-n, --name <new_name>
Sets a new name for the virtual network.
--ip <ip[/mask]>
Sets an IPv4 address and subnet mask for the Parallels virtual network adapter.
--dhcp-server <on | off>
Enables or disables the Parallels virtual DHCPv4 server.
--dhcp-ip <ip>
Sets an IPv4 address for the Parallels virtual DHCPv4 server.
--ip-scope-start <ip>
Sets the start IPv4 address for the pool of IPv4 addresses.
--ip-scope-end <ip>
Sets the end IPv4 address for the pool of IPv4 addresses.
--ip6 <ip[/mask]>
Sets an IPv6 address and subnet mask for the Parallels virtual network adapter.
--dhcp6-server <on | off>
Enables or disables the Parallels virtual DHCPv6 server.
--dhcp-ip6 <ip>
Sets an IPv6 address for the Parallels virtual DHCPv6 server.
--ip6-scope-start <ip>
Sets the start IPv6 address for the pool of IPv6 addresses.
--ip6-scope-end <ip>
Sets the end IPv6 address for the pool of IPv6 addresses.
--host-assign-ip6 <on | off>
Sets whether the host interface for this network will have IPv6 address.
--connect-host-to-net <on | off>
Connects the host to the current Parallels virtual network adapter.
--nat-<tcp | udp>-add <rule_name, src_port,<dest_ip | dest_vm>, dest_port>
Adds a new port forwarding rule. The options are:
rule_name: a rule name.
src_port: port number for incoming connections.
dest_ip: an IP address to which incoming connections will be forwarded.
dest_vm: the name or UUID of the virtual machine to which incoming connections will be forwarded.
dest_port: port number to which incoming connections will be forwarded.
--nat-<tcp | udp>-del <rule_name>
Deletes the specified port forwarding rule.
web-portal signin <email>
Sign in to your Parallels account. The <email> parameter specifies your registered email address. When prompted, enter your Parallels account password. You can also specify a file containing the password using an optional parameter (see below).
This command must be used before you activate Parallels Desktop Pro or Standard editions from the command line using the install-license command.
Optional parameters
-p,--read-passwd <path>
Specifies a text file with your Parallels account password.
Related commands
web-portal signout
Signs you out of your Parallels account.
info --web-portal
Displays the information about whether you are signed in to your Parallels account and lists details if you are.
You can start a debugging session directly from Parallels Desktop. When the virtual machine is running, click the Develop menu in the macOS menu bar and choose Start Debugging Session.
Note: Parallels Desktop supports lldb as a debugging front end. It should be installed with the XCode command line tools or XCode, and you must accept the lldb license agreement.
prlsrvctl usb list [-j, --json] [-c, --compat] [-a, --all]
Lists USB devices installed on the server together with the information on their assignments for the current user. In the compat mode all known USB devices are listed, showing the device name, device ID and autoconnect options. In the new mode (without the [-c, --compat] option), some additional information about the device is shown, such as whether the device is connected to a VM at the current moment. By default, only currently plugged to host devices are shown. To see all devices, call with the [-a, --all] option.
prlsrvctl usb set <usb_dev_id> <vm_uuid | vm_name> | [--autoconnect <ask | host>] | [--vm <vm_uuid | vm_name>]
Either assigns a USB device with ID <usb_dev_id> to the specified virtual machine or configures the action for this device (suggest to connect to active VM or silently connect to host). When the device is configured to connect to a virtual machine, this USB device will be connected to the specified virtual machine when you start the virtual machine or attach the device to the host computer.
prlsrvctl usb del <usb_dev_id>
Removes a specified USB device assignment.
prlsrvctl usb cleanup
Cleans up the database of known USB devices. Sometimes the database becomes broken or too big. This command rebuilds the USB devices database.
The prlsrvctl utility returns 0 on success or an error code on failure.
prlsrvctl problem-report <-d, --dump | -s, --send [--proxy <user[:password]@proxyhost[:port]> | --no-proxy]>
Generates a problem report. If the -s, --send option is specified, sends the report to Parallels. The --proxy parameter specifies Internet proxy settings if you are using one to connect to the Internet.
Optional parameters
--stand-alone
Assembles a report without connecting to the Parallels Desktop service.
--name <user_name>
Appends the user name to the report.
--email <user_email>
Appends the user email address to the report.
--description <problem_description>
Appends a free-form description to the report.
prlsrvctl shutdown [-f, --force]
Shuts down Parallels Desktop. The command correctly stops all services. The optional -f, --force parameter forcibly shuts down Parallels Desktop and hard-stops services if necessary.
The prlctl utility is used to perform management tasks on virtual machines. The utility supports a full range of tasks from creating and administering virtual machines to getting statistics and generating problem reports.
The general syntax is as follows:
prlctl command <vm_ID | vm_name> [options] [-v, --verbose number]
The parameters are:
command: one of the available commands.
vm_ID | vm_name: ID or name of the target virtual machine.
options: command options.
-v, --verbose number: Show verbose output. The greater the number, the more verbose output will be produced.
The subsequent sections describe the available prlctl commands grouped by functionality.
prlctl create <vm_name> --ostemplate <name>
Creates a virtual machine from the specified virtual machine template. The --ostemplate <name> parameter specifies the source template name. To obtain the list of available templates, use the prlctl list -t command.
--dst
A path to the directory where the virtual machine files will be stored. If omitted, the default location will be used.
prlctl create <vm_name> [-o,--ostype <name | list>]
Creates a virtual machine and optimizes it for the OS type specified in the --ostype option. If the --ostype parameter is omitted, the virtual machine is optimized for Windows 10 by default. If you want to optimize the virtual machine for a different OS type, use the list option to get the list of available OS types: prlctl create vm_name -o list, then select a desired OS type name and use it as a value of the -o parameter.
prlctl create <vm_name> -d,--distribution <name | list>
Creates a virtual machine and optimizes it for the OS distribution specified in the --distribution option. Use the list option to get the list of available distributions: prlctl create vm_name -d list, then select a desired distribution name and use it as a value of the -o parameter.
Common optional parameters
--no-hdd
Create a virtual machine without hard disk drives.
--lion-recovery
Create a virtual machine from the Lion OS host recovery partition.
To create a macOS virtual machine, download a .ipsw file with macOS installation image, and execute the command with the following parameters:
prlctl create <macOS_VM_name> -o macos --restore-image <path to the .ipsw file>
E.g., prlctl create "macOS_beta" -o macos --restore-image /Users/{user_account}/Downloads/UniversalMac_14.5_23F79_Restore.ipsw
Note: Since virtual machines on Apple Silicon Macs only work via Apple's own Virtualization Framework, there are compatibility limitations between different macOS versions on your Mac and virtual machines. The only scenario that is guaranteed to work is running the same major version of macOS on your virtual machine as on your Mac computer. For more information on possible limitations of macOS virtual machines on Apple Silicon Macs, please refer to this knowledge base article.
By default, the virtual machine is created with 64GB of disk space. If you want to create a machine with a different disk size, the process is slightly different:
Having downloaded a .ipsw installation file, run the following command: prlctl create <macOS_VM_name> -o macos --no-hdd --restore-image <path to the .ipsw file> This command will create a virtual machine shell with no hard drive.
Use the following command to add a virtual hard drive and specify its size (in megabytes): prlctl set <macOS_VM_name> --device-add hdd --type plain --size <size_in_megabytes> Note that only plain drive type is currently supported for macOS virtual machines on Apple Silicon Macs. For more information on supported virtual drive types, refer to this chapter of the guide.
Start the installation process by executing the following command: prlctl start <macOS_VM_name>
Wait for the installation to complete and follow on-screen instructions to choose language, create a user account, etc.
Fetch the .ipsw file download URL by executing the following command in the Terminal: /Applications/Parallels\ Desktop.app/Contents/MacOS/prl_macvm_create --getipswurl
Copy the resulting URL and open it in your browser to download the .ipsw file.
Once the file has been downloaded, execute the following command in the Terminal: /Applications/Parallels\ Desktop.app/Contents/MacOS/prl_macvm_create <path_to_ipsw> <path_to_macVM> --disksize <size_in_bytes> E.g., /Applications/Parallels\ Desktop.app/Contents/MacOS/prl_macvm_create ~/Downloads/UniversalMac_13.3_22E252_Restore.ipsw ~/Parallels/macOS.macvm --disksize 80000000000
Wait for the installation process to complete.
Once finished, locate the file in ~/Parallels/ (your home folder > "Parallels"), drag and drop it to Control Center, or open it with Parallels Desktop via Finder.
Note: In this process, once your macOS VM is created, you won't be able to change the size of its virtual hard drive.
Syntax 1
prlctl list
Lists existing virtual machines. By default (when no parameters are included), only running VMs are displayed.
Optional parameters
-a, --all
Lists all existing virtual machines regardless of their state (running, stopped, suspended, etc.).
-f, --full
Shows the real IP address(es) for running virtual machines.
-o, --output field [, field...]
Displays only the specified field(s).
-s, --sort <field | -field>
Sorts by field (arguments are the same as those for -o). Add "-" (minus sign) before the field name to reverse the sort order.
-L
Lists fields which can be used for both the output (-o, --output) and sort order (-s, --sort) options.
-t, --template
Include templates in the output.
-j, --json
Produces output in JSON format.
Syntax 2
list -i, --info
Displays the VM configuration information. By default, the information for all existing VMs is shown.
Optional parameters
-f, --full
Shows the real IP address(es) for running virtual machines.
-j, --json
Produces output in JSON format.
vm_id | vm_name
Returns the information about a VM specified by ID or name.
The prlctl utility is used to perform management tasks on virtual machines. The utility supports a full range of tasks from creating and administering virtual machines to getting statistics and generating problem reports.
The general syntax is as follows:
prlctl command <vm_ID | vm_name> [options] [-v, --verbose number]
The parameters are:
command: one of the available commands.
vm_ID | vm_name: ID or name of the target virtual machine.
options: command options.
-v, --verbose number: Show verbose output. The greater the number, the more verbose output will be produced.
The subsequent sections describe the available prlctl commands grouped by functionality.
prlctl delete <vm_id | vm_name>
Deletes a virtual machine. The command removes a virtual machine from Parallels Desktop and permanently deletes all its files from the host computer. Once completed, this operation cannot be reversed.
prlctl clone <vm_id | vm_name> --name <new_name>
Clones (makes an exact copy of) a specified virtual machine. The -name <new_name> parameter specifies a name to give to the new virtual machine.
--template
Make the new virtual machine a template.
--dst
Set the path to the directory where the virtual machine files will be stored. If omitted, the default location will be used.
--regenerate-src-uuid
Regenerate the virtual machine source ID (the SMBIOS product ID will also be changed).
--linked
Create a linked clone.
-i, --id <snapid>
Create a linked clone based on a snapshot with a given snapid.
--detach-external-hdd <yes | no>
Specifies what to do with hard disks located outside the source virtual machine file. If you specify yes, outside hard disks will be removed from the destination VM. If you specify no, outside hard disks will remain in the new VM. Please note that in either case, the outside hard disks will NOT be copied to the destination.
prlctl register <path>
Registers a virtual machine in Parallels Desktop. The <path> parameter specifies a path to the virtual machine file.
--uuid <UUID>
If included, the specified UUID will be assigned to the virtual machine. A UUID can be generated using console utilities like uuidgen(1)
in macOS. If this option is not included, the original UUID will be used.
--regenerate-src-uuid
If included, the virtual machine source ID will be automatically generated (the SMBIOS product ID will be changed as well).
--force
If included, all validation checks will be skipped.
prlctl unregister <vm_id | vm_name>
Unregisters the specified virtual machine.
Notes: Use the register command when you have a virtual machine on the host that doesn't show up in the list of the virtual machines registered with Parallels Desktop. This can be a machine that was previously removed from Parallels Desktop or a machine that was manually copied from another location.
Once a VM is registered, all VM restrictions on the filesystem are removed. If you would like to protect the VM from editing, you should restrict registering or removing the VM in Parallels Desktop preferences.
The unregister command removes a virtual machine from Parallels Desktop but does not delete it from the host. You can re-register such a machine with Parallels Desktop later using the register command.
prlctl move <vm_id | vm_name> --dst <path>
Moves the files of a specified virtual machine to a location specified in the -dst parameter on the same computer. The command supports moving only stopped and suspended virtual machines.
prlctl convert <path>
This command is used to convert a third-party virtual machine to a Parallels virtual machine. The <path> parameter specifies a path to the original virtual machine.
Note: Importing, converting, and running previously created virtual machines from another virtualization application is not available on Apple Silicon Macs.
--dst <path>
A path where the converted virtual machine files will be stored. If omitted, the default virtual machine location will be used.
--force
If included, the virtual machine conversion will continue even if the guest OS cannot be identified.
Note: The following third-party virtual machines and disks are supported:
Microsoft Hyper-V
Microsoft Virtual PC
Virtual Box
VMware
prlctl installtools <vm_id | vm_name>
Installs Parallels Tools in the specified virtual machine. To use this command, the target virtual machine must be running.
prlctl enter <vm_id | vm_name>
Logs in to the virtual machine. The command creates a command prompt channel to a virtual machine and allows you to execute commands in it. Parallels Tools must be installed in the virtual machine.
--current-user or --user <user_name>
Include the --current-user option to log in as the user currently logged in inside the guest OS, or use the --user parameter and specify a user name.
--password <password>
The user password.
prlctl exec <vm_id | vm_name> <command>
Executes a command inside a virtual machine. Parallels Tools must be installed in the virtual machine. Commands in Linux guests are invoked with bash -c.
--current-user or --user <user_name>
Include the --current-user option to log in as the user currently logged in inside the guest OS; or use the --user parameter and specify a user name.
--password <password>
The user password
-r, --resolve-paths
Enable converting host paths to guest.
prlctl send-key-event <VM ID> -k,--key <key> | -s,--scancode <scancode> [-e,--event <press|release>] [-d,--delay <msec>]
Sends a single keyboard event (key press or release) identified with a specific key code or scancode to a specified virtual machine with a specified delay (in milliseconds). For the complete list of key codes, see this subchapter.
prlctl send-key-event <VM ID> -j,--json
Sends a sequence of keyboard events by reading JSON input from stdin. Example of the format is:
This table contains the numeric values for the key events used in the -k
option of the prlctl
send-key-event
command.
PRL_KEY_WILDCARD_ANY
1
PRL_KEY_WILDCARD_KEYBOARD
2
PRL_KEY_WILDCARD_MOUSE
3
PRL_KEY_WILDCARD_SHIFT
4
PRL_KEY_WILDCARD_CTRL
5
PRL_KEY_WILDCARD_ALT
6
PRL_KEY_WILDCARD_WIN
7
PRL_KEY_ESCAPE
9
PRL_KEY_1
10
PRL_KEY_2
11
PRL_KEY_3
12
PRL_KEY_4
13
PRL_KEY_5
14
PRL_KEY_6
15
PRL_KEY_7
16
PRL_KEY_8
17
PRL_KEY_9
18
PRL_KEY_0
19
PRL_KEY_MINUS
20
PRL_KEY_EQUAL
21
PRL_KEY_BACKSPACE
22
PRL_KEY_TAB
23
PRL_KEY_Q
24
PRL_KEY_W
25
PRL_KEY_E
26
PRL_KEY_R
27
PRL_KEY_T
28
PRL_KEY_Y
29
PRL_KEY_U
30
PRL_KEY_I
31
PRL_KEY_O
32
PRL_KEY_P
33
PRL_KEY_LEFT_BRACKET
34
PRL_KEY_RIGHT_BRACKET
35
PRL_KEY_ENTER
36
PRL_KEY_LEFT_CONTROL
37
PRL_KEY_A
38
PRL_KEY_S
39
PRL_KEY_D
40
PRL_KEY_F
41
PRL_KEY_G
42
PRL_KEY_H
43
PRL_KEY_J
44
PRL_KEY_K
45
PRL_KEY_L
46
PRL_KEY_SEMICOLON
47
PRL_KEY_QUOTE
48
PRL_KEY_TILDA
49
PRL_KEY_LEFT_SHIFT
50
PRL_KEY_BACKSLASH
51
PRL_KEY_Z
52
PRL_KEY_X
53
PRL_KEY_C
54
PRL_KEY_V
55
PRL_KEY_B
56
PRL_KEY_N
57
PRL_KEY_M
58
PRL_KEY_COMMA
59
PRL_KEY_DOT
60
PRL_KEY_SLASH
61
PRL_KEY_RIGHT_SHIFT
62
PRL_KEY_NP_STAR
63
PRL_KEY_LEFT_ALT
64
PRL_KEY_SPACE
65
PRL_KEY_CAPS_LOCK
66
PRL_KEY_F1
67
PRL_KEY_F2
68
PRL_KEY_F3
69
PRL_KEY_F4
70
PRL_KEY_F5
71
PRL_KEY_F6
72
PRL_KEY_F7
73
PRL_KEY_F8
74
PRL_KEY_F9
75
PRL_KEY_F10
76
PRL_KEY_NUM_LOCK
77
PRL_KEY_SCROLL_LOCK
78
PRL_KEY_NP_7
79
PRL_KEY_NP_8
80
PRL_KEY_NP_9
81
PRL_KEY_NP_MINUS
82
PRL_KEY_NP_4
83
PRL_KEY_NP_5
84
PRL_KEY_NP_6
85
PRL_KEY_NP_PLUS
86
PRL_KEY_NP_1
87
PRL_KEY_NP_2
88
PRL_KEY_NP_3
89
PRL_KEY_NP_0
90
PRL_KEY_NP_DELETE
91
PRL_KEY_PRINT
92
PRL_KEY_EUROPE_1
93
PRL_KEY_EUROPE_2
94
PRL_KEY_F11
95
PRL_KEY_F12
96
PRL_KEY_HOME
97
PRL_KEY_UP
98
PRL_KEY_PAGE_UP
99
PRL_KEY_LEFT
100
PRL_KEY_RIGHT
102
PRL_KEY_END
103
PRL_KEY_DOWN
104
PRL_KEY_PAGE_DOWN
105
PRL_KEY_INSERT
106
PRL_KEY_DELETE
107
PRL_KEY_NP_ENTER
108
PRL_KEY_RIGHT_CONTROL
109
PRL_KEY_PAUSE
110
PRL_KEY_NP_SLASH
112
PRL_KEY_RIGHT_ALT
113
PRL_KEY_LEFT_WIN
115
PRL_KEY_RIGHT_WIN
116
PRL_KEY_MENU
117
PRL_KEY_MEDIA_NEXT_TRACK
118
PRL_KEY_MEDIA_PREV_TRACK
119
PRL_KEY_MEDIA_STOP
120
PRL_KEY_MEDIA_PLAY_PAUSE
121
PRL_KEY_MUTE
122
PRL_KEY_VOLUME_UP
123
PRL_KEY_VOLUME_DOWN
124
PRL_KEY_MEDIA_SELECT
125
PRL_KEY_APP_MAIL
126
PRL_KEY_APP_CALCULATOR
127
PRL_KEY_APP_MY_COMPUTER
128
PRL_KEY_WWW_SEARCH
129
PRL_KEY_WWW_HOME
130
PRL_KEY_WWW_BACK
131
PRL_KEY_WWW_FORWARD
132
PRL_KEY_WWW_STOP
133
PRL_KEY_WWW_REFRESH
134
PRL_KEY_WWW_FAVORITES
135
PRL_KEY_EJECT
136
PRL_KEY_SYSTEM_POWER
137
PRL_KEY_SYSTEM_SLEEP
138
PRL_KEY_SYSTEM_WAKE
139
PRL_KEY_BRAZILIAN_KEYPAD
140
PRL_KEY_RO
141
PRL_KEY_HIRAGANA_KATAKANA
142
PRL_KEY_YEN
143
PRL_KEY_HENKAN
144
PRL_KEY_MUHENKAN
145
PRL_KEY_PC9800_KEYPAD
146
PRL_KEY_HANGUEL
147
PRL_KEY_HANJA
148
PRL_KEY_KATAKANA
149
PRL_KEY_HIRAGANA
150
PRL_KEY_ZENKAKU_HANKAKU
151
PRL_KEY_F13
152
PRL_KEY_F14
153
PRL_KEY_F15
154
PRL_KEY_F16
155
PRL_KEY_F17
156
PRL_KEY_F18
157
PRL_KEY_F19
158
PRL_KEY_F20
159
PRL_KEY_F21
160
PRL_KEY_F22
161
PRL_KEY_F23
162
PRL_KEY_F24
163
PRL_KEY_NP_EQUAL
164
PRL_KEY_BREAK
165
PRL_KEY_PRINT_WITH_MODIFIER
166
PRL_KEY_SYSRQ
167
PRL_KEY_FN
168
PRL_KEY_EURO
169
PRL_KEY_DOLLAR
170
PRL_KEY_MON_BRIGHTNESS_DOWN
171
PRL_KEY_MON_BRIGHTNESS_UP
172
PRL_KEY_APP_EXPOSE
173
PRL_KEY_APP_DASHBOARD
174
PRL_KEY_KBD_BRIGHTNESS_DOWN
175
PRL_KEY_KBD_BRIGHTNESS_UP
176
PRL_KEY_MAC129
177
PRL_KEY_LEFT_BUTTON
178
PRL_KEY_MIDDLE_BUTTON
179
PRL_KEY_RIGHT_BUTTON
180
PRL_KEY_MOVE_UP_LEFT
181
PRL_KEY_MOVE_UP
182
PRL_KEY_MOVE_UP_RIGHT
183
PRL_KEY_MOVE_LEFT
184
PRL_KEY_MOVE_RIGHT
185
PRL_KEY_MOVE_DOWN_LEFT
186
PRL_KEY_MOVE_DOWN
187
PRL_KEY_MOVE_DOWN_RIGHT
188
PRL_KEY_WHEEL_UP
189
PRL_KEY_WHEEL_DOWN
190
PRL_KEY_WHEEL_LEFT
191
PRL_KEY_WHEEL_RIGHT
192
prlctl capture <vm_id | vm_name> --file <name>
Captures a screen area of a virtual machine to a file in PNG format. The --file <name> parameter specifies the target file name and path.
prlctl status <vm_id | vm_name>
Displays the status of the specified virtual machine.
prlctl protection-set <vm_id | vm_name>
Protects the specified encrypted virtual machine expiration date settings with a password.
prlctl protection-remove <vm_id | vm_name>
Disables password protection of the specified encrypted virtual machine expiration date settings.
prlctl archive <vm_id | vm_name>
Archives the specified virtual machine bundle.
prlctl unarchive <vm_id | vm_name>
Unarchives the specified virtual machine bundle.
prlctl start <vm_id | vm_name>
Starts the specified virtual machine. The start command can be used to start a stopped virtual machine or to resume a paused virtual machine.
prlctl resume <vm_id | vm_name>
Resumes the specified virtual machine.
prlctl pause <vm_id | vm_name>
Pauses the specified virtual machine.
prlctl suspend <vm_id | vm_name>
Suspends the specified virtual machine.
prlctl restart <vm_id | vm_name>
Restarts the specified virtual machine. The restart command first gracefully shuts down a virtual machine and then starts it again.
prlctl reset <vm_id | vm_name>
Resets the specified virtual machine. The reset command first performs a 'hard' virtual machine shutdown and then starts it again.
prlctl reset-uptime <vm_id | vm_name>
Resets the specified virtual machine uptime counter (the counter start date/time will also will be reset with this action).
prlctl stop <vm_id | vm_name> [--kill] [--drop-state]
Stops the specified virtual machine. You can use the --kill option to forcibly stop the VM. The stop command can perform a 'hard' or a graceful virtual machine shutdown. If the --kill
parameter is included, the 'hard' shutdown will be performed. If the parameter is omitted, the outcome of the graceful shutdown attempt will depend on the following:
- If the Parallels Tools package is installed in a virtual machine, the graceful shutdown will be performed using its facilities.
- If the Parallels Tools package is not installed, the command will try to perform a graceful shutdown using ACPI. Depending on the ACPI support availability in the guest operating system, this may work or not.
Use the --drop-state parameter to reset the specified VM from a suspended state to being completely shut down. Activating this option ensures that the specified VM starts afresh next time, completing the entire boot-up process.
Note: These commands are not supported for macOS virtual machines.
prlctl encrypt <vm_id | vm_name> [--dry-run]
Encrypts the specified virtual machine. You can use the the --dry-run option to check preconditions for successful encryption. The encrypt command will encrypt the specified virtual machine and all its data. A user will be prompted to enter an encryption password after the command is executed. The password will be required to decrypt the virtual machine later. The encryption password can be modified for an encrypted virtual machine using the change-passwd command (see below).
prlctl decrypt <vm_id | vm_name> [--dry-run]
Decrypts the specified encrypted virtual machine. You can use the --dry-run option to check preconditions for successful decryption. The decrypt command will decrypt the specified virtual machine. A user will have to enter a password that was specified when the virtual machine was encrypted.
prlctl change-passwd <vm_id | vm_name>
Changes the encryption password for the specified virtual machine. A user will be asked to enter the current and the new password.
--cpus <num>
Sets the number of CPUs to be available to the virtual machine.
--memsize <num>
Sets the amount of memory for the virtual machine (in megabytes).
This section describes prlctl set command options that you can use to configure a virtual machine.
The general syntax is as follows:
prlctl set <vm_id | vm_name> [options]
The prlctl set command is used to modify the configuration of a virtual machine and manage virtual machine devices and shared folders. The subsequent subsections describe parameters and options that can be used with this command to perform a variety of virtual machine configuration management tasks.
Note: This subset of parameters is not supported for macOS virtual machines.
--videosize <num>
Sets the amount of memory for the virtual machine graphic card (in megabytes).
--3d-accelerate <off | highest | dx9>
Sets 3d acceleration video mode.
--vertical-sync <on | off>
Enables or disables vertical synchronization.
--high-resolution <on | off>
Enables or disables high resolution video mode for retina display.
--device-bootorder <"name1 name2 ...">
Specifies the order of boot devices for the virtual machine. Supported devices are HDD, CD/DVD, or external storage. A device name can be obtained using the prlctl list -i command.
--efi-boot <on | off>
This sets the EFI boot options. Specify on to boot using the EFI firmware, or specify off to boot using the BIOS firmware (the default).
--select-boot-device <on | off>
Enables or disables selecting a boot device at the virtual machine startup.
--external-boot-device <name>
Sets an external device from which to boot the virtual machine.
--smart-mouse-optimize <auto | on | off>
Sets smart mouse optimization mode.
--sticky-mouse <on | off>
Enables or disables the sticky mouse option.
--keyboard-optimize <auto | accessibility | on | off>
Sets a keyboard optimization mode.
--smart-mount <on | off>
Enables or disables shared volumes.
--shared-profile <on | off>
Enables or disables shared profile.
--shared-cloud <on | off>
Enables or disables shared cloud.
--sh-app-guest-to-host <on | off>
Enables or disables sharing guest applications with the host.
--show-guest-app-folder-in-dock <on | off>
Enables or disables showing the folder with guest OS applications in the Dock.
--sh-app-host-to-guest <on | off>
Enables or disables sharing host applications with guests.
--shared-clipboard <on | host-to-guest | guest-to-host | off>
Note: This command is not yet supported for macOS virtual machines running on Apple Silicon Macs. The shared clipboard is enabled by default on macOS virtual machines.
Controls the availability of clipboard contents between the Mac and Windows/Linux virtual machines.
--sync-host-printers <on | off>
Enables or disables using host printers in Windows guests (starting from Windows 2000).
--sync-default-printer <on | off>
Synchronizes host's default printer with Windows default printer.
--faster-vm <on | off>
Sets the performance mode: faster virtual machine or faster host.
--adaptive-hypervisor <on | off>
Enables or disables adaptive hypervisor.
--disable-winlogo <on | off>
Enables or disables the Windows logo.
--auto-compress <on | off>
Enables or disables automatic compression of virtual disks.
--nested-virt <on | off>
Enables or disables nested virtualization.
--pmu-virt <on | off>
Enables or disables PMU virtualization.
--longer-battery-life <on | off>
Sets a power option: longer battery life or better performance.
--battery-status <on | off>
Shows or hide battery status.
--resource-quota <low | medium | unlimited>
Sets the virtual machine resource quota:
low: The host takes priority in resources.
medium: The host and the virtual machine share resources evenly.
unlimited: The virtual machine uses the maximum possible resources.
--autostart <off | open-window | start-app | start-host | user-login>
Sets the virtual machine autostart options:
off: The virtual machine is started manually.
open-window: The virtual machine starts when its window opens.
start-app: The virtual machine starts when Parallels Desktop starts.
start-host: The virtual machine is started automatically on the host boot.
user-login: The virtual machine is started automatically on user logon.
--autostart-delay <n>
Sets the delay of the virtual machine autostart on host boot to n seconds.
--autostop <stop | suspend | shutdown>
Specifies what should happen to the virtual machine on host shutdown.
--startup-view <same | window | coherence | fullscreen | modality | headless>
Sets the virtual machine startup view options:
same: Same as the last time
window: Normal window
coherence: Coherence
fullscreen: Full screen
modality: Modality
headless: Headless
--on-shutdown <window | close | quit>
Sets the virtual machine shutdown options:
window: The virtual machine window stays open after the virtual machine is shut down.
close: The virtual machine window closes after the virtual machine is shut down.
quit: Parallels Desktop quits after the virtual machine is shut down.
--on-window-close <suspend | shutdown | stop | ask | keep-running>
Sets the virtual machine window close options:
suspend: The virtual machine is suspended after its window is closed.
shutdown: The virtual machine is shut down after its window is closed.
stop: The virtual machine is forcibly stopped after its window is closed.
ask: Ask the user what to do: suspend, shut down, or stop the virtual machine.
keep-running: The virtual machine is kept running after its window is closed.
--pause-idle <on | off>
Enables or disables pausing of an idle virtual machine.
--undo-disks <off | discard | ask>
Sets the virtual machine undo disks options:
off: Undo disks mech is off.
discard: Discard all changes made in the virtual machine after it is stopped.
ask: Ask the user what to do: apply changes or discard them after the virtual machine is stopped.
--auto-share-camera <on | off>
Enables or disables automatic Web camera sharing.
--auto-share-bluetooth <on | off>
Enables or disables automatic sharing of Bluetooth devices.
--support-usb30 <on | off>
Enables or disables USB 3.0 support.
--winsystray-in-macmenu <on | off>
Shows the Windows notification area in the Mac menu bar.
--auto-switch-fullscreen <on | off>
Allows applications to auto-switch to full screen.
--disable-aero <on | off>
Enables or disables Windows Aero.
--hide-min-windows <on | off>
Allows to hide minimized windows.
--require-pwd <exit-fullscreen | change-vm-state | manage-snapshots | change-guest-pwd | change-vm-config>:<on | off>
Require an administrator password to perform a corresponding action. Use --allow-to-confirm to make the system ask for username and password.
--require-custom-pwd <exit-fullscreen | change-vm-state | manage-snapshots | change-guest-pwd | change-vm-config>:<on | off>
Require a custom password to perform an operation. The change-guest-pwd option allows you to change the guest OS password via command line. Use --allow-to-confirm to make the system ask for username and password. Other options are self-explanatory.
--custom-pwd [--custom-pwd-mode <on | off | change>] [--replace-commands]
Set, reset, or changes a custom password for operations that require it. The options are described below.
--custom-pwd-mode < on | off | change> — set, reset, or change a custom password for operations that require it.
--allow-to-confirm [--host-admin] — prompt to enter admin credentials or a custom password if an operation requires it. If no operation requires a password, this option will be ignored. If an operation requires a password, this option shows a prompt to enter it. If an operation requires a password, but this option is omitted, the operation will fail with a corresponding error. To make an operation require a password, use the following options: --require-pwd , --require-custom-pwd, or --lock-edit-settings as described in this guide. --host-admin specifies the host administrator name if an administrator password is required to unlock the Parallels Desktop preferences for editing.
--replace-commands — specify this option to reset commands that are protected with the admin password. This means that when you enable a custom password, commands that require the admin password will now require a custom password. Commands that previously required a custom password will be discarded. The same logic is used when you switch back to the admin password (set --custom-pwd-mode to off). When you disable a custom password, commands that require it will now require the admin password. Commands that previously required the admin password will be discarded. This option is ignored if --custom-pwd-mode is set to change.
--lock-on-suspend <on | off>
Always locks the guest OS on suspend.
--isolate-vm <on | off>
Isolates the the virtual machine from the host.
--smart-guard <on | off>
Enables or disables smart guard mech.
--sg-notify-before-create <on | off>
Notifies the user before creating a snapshot.
--sg-interval <seconds>
Sets a time interval between taking snapshots.
--sg-max-snapshots <num>
Sets the maximum allowed number of snapshots.
--lock-edit-settings <on | off [--host-admin <name>]>
Locks or unlocks editing of the virtual machine configuration.
--host-admin <name>
Specifies the host administrator name if an administrator password is required to unlock editing of the virtual machine configuration.
--userpasswd <user : passwd> [--host-admin <name>]
Sets a password for the specified user in the virtual machine. If the user account does not exist, it is created. The --host-admin <name> parameter specifies the host administrator name if an administrator password is required to change the user password in the virtual machine. Parallels Tools must be installed in the virtual machine for the command to succeed.
--password-to-edit
Note: This parameter has been dropped in Parallels Desktop 15. In previous versions, it was used to set a custom password to modify the virtual machine configuration. In Parallels Desktop 15 and newer, use the --require-custom-pwd and --custom-pwd commands (described at the beginning of this section).
--expiration <<on|off>|date:<yyyy-MM-ddThh:mm:ss>|time-check:<seconds>|offline-time:<seconds>|time-server:<url>|note:<text>>
Expiration date parameters:
on|off: Enables or disables expiration date checking.
date: Sets a date and time when the virtual machine usage period expires (e.g., 2024-12-31T20:30:00).
time-check: Sets how often (in seconds) Parallels Desktop contacts the time server to check the expiration date and time.
offline-time: Sets the time period (in seconds) during which a user can work with the virtual machine if Parallels Desktop is unable to check the expiration date and time.
time-server: Specifies the URL of a trusted time server to check the expiration date and time.
note: Adds a note (e.g., system administrator contact info).
--device-add hdd [--image <image_name>] [--type <expand | plain>] [--size <n>] [--split]
[--iface <ide | scsi | sata>] [--position <n>]
[--subtype <buslogic | lsi-spi | lsi-sas>]
[--online-compact <on | off>]
--device-set <hdd_name> [--image <image_name>] [--type <expand | plain>]
[--size <n>] [--split] [--iface <ide | scsi | sata>] [--position <n>]
[--subtype <buslogic | lsi-spi | lsi-sas>] [--online-compact <on | off>]
hdd_name: The name of the virtual hard drive to modify (--device-set command only). Virtual hard drives are named using the hddN format, where N is the drive index number starting from 0 (e.g., hdd0, hdd1). To obtain the list of disk names, use the prlctl list --info
command.
--image: specifies the name of the file to be used for emulating the VM virtual disk drive. If this option is omitted, a new file is created inside the directory storing all VM-related configuration files and assigned the name of harddiskN.hdd
.
--type: specifies the type of the virtual disk from one of the following:
expand (default): virtual disks of this type are small initially and grow in size as you add data to it.
plain: virtual disks of this type have a fixed size from the moment of their creation.
--size: hard disk size, in megabytes.
--split: splits the hard disk into 2GB pieces.
--iface: virtual hard disk interface type: ide, scsi, or sata.
--position: the SCSI / IDE / SATA device identifier to be used for the disk drive. Allowed ranges:
0-3 for IDE disk drives
0-6 for SCSI disk drives
0-5 for SATA disk drives
--subtype: virtual hard disk subtype: buslogic, lsi-spi, lsi-sas.
--online-compact: enables or disables virtual hard disk online compact mode.
The general syntax for adding a device is as follows:
prlctl set <vm_id | vm_name> --device-add <hdd | cdrom | net | fdd | serial | parallel | sound | usb> [device_options]
To modify a device:
prlctl set <vm_id | vm_name> --device-set <device_name> [device_options]
The subsequent sections describe options and parameters for each device type.
The options described here are common for all types of devices.
--device-connect <device_name>
Connects the specified device to a running virtual machine. The device can be of type fdd, cdrom, sound, or net. To obtain a device name, use the prlctl list -i command.
--device-disconnect <device_name>
Disconnects the specified device from a running virtual machine.
--device-set <device_name> <<--enable | --disable> | <--connect | --disconnect>>
Enables/disables or connects/disconnects the specified device to/from a virtual machine. Please note that the --device-set command is also used to modify a device configuration and has additional parameters, which are different for different types of devices. The parameters for each device type are described in subsequent sections of this guide.
--device-del <device_name> [--detach-only | --destroy-image | --destroy-image-force]
Removes the specified device from the virtual machine.
If --detach-only is specified and the device is a virtual hard disk drive, the disk image is preserved.
If --destroy-image is specified, the virtual HDD image is removed from the server.
If --destroy-image-force is specified, the virtual HDD image is removed from all snapshots and from the server.
The default action on deleting a virtual HDD is to detach the HDD image as if --detach-only was specified.
Note: Adding virtual optical drives is not supported in macOS virtual machines.
--device-add cdrom [--image <name>] [--iface <ide | scsi | sata>] [--position <n>]
[--subtype <buslogic | lsi-spi | lsi-sas>]
--device-set <drive_name> [--image <name>] [--iface <ide | scsi | sata>]
[--position <n>] [--subtype <buslogic | lsi-spi | lsi-sas>]
drive_name: The name of the optical drive to modify (--device-set command only). To obtain the list of the available drives, use the prlctl list --info
command.
--image: connect the specified image file to the virtual machine. The following image file formats are supported: iso, cue, ccd, dmg.
--iface: virtual optical interface type: ide, scsi, sata.
--position: the SCSI / IDE / SATA device identifier to be used for the optical drive. Allowed ranges:
0-3 for IDE disk drives
0-6 for SCSI disk drives
0-5 for SATA disk drives
--subtype: virtual optical drive subtype: buslogic, lsi-spi, lsi-sas.
Note: Adding virtual floppy drives is not supported in macOS virtual machines.
The command adds a virtual floppy disk drive based on a file image.
--device-add fdd --image <image> [--recreate]
--device-set <fdd_name> --image <image> [--recreate]
fdd_name: The name of the FDD to modify. To obtain the list of the available drives, use the prlctl list --info
command.
--image: specifies the image file.
--recreate: if included, recreates the image file if it exists.
--device-add hdd --device <real_name> [--iface <ide | scsi | sata>] [--passthr <yes | no>]
[--position <n>] [--subtype <buslogic | lsi-spi | lsi-sas>]
--device: the name of the host computer hard drive that will be connected to the virtual machine. To obtain the names of all hard disks installed on the host, use the prlsrvctl info command.
--iface: virtual hard disk interface type: ide, scsi, sata.
--passthr: enables the passthrough mode for the specified device.
--position: the SCSI / IDE / SATA device identifier to be used for the drive. Allowed ranges:
0-3 for IDE disk drives
0-6 for SCSI disk drives
0-5 for SATA disk drives
--subtype: virtual hard disk subtype: buslogic, lsi-spi, lsi-sas.
--device-add cdrom --device <name> [--iface <ide | scsi | sata>] [--passthr <yes | no>]
[--position <n>] [--subtype <buslogic | lsi-spi | lsi-sas>]
--device: the name of the host computer's optical drive that will be connected to the virtual machine. To obtain the names of all optical drives installed on the host, use the prlsrvctl info command.
--iface: virtual optical drive interface type.
--passthr: enables the passthrough mode for the specified device.
--position: the SCSI / IDE / SATA device identifier to be used for the drive. Allowed ranges:
0-3 for IDE disk drives
0-6 for SCSI disk drives
0-5 for SATA disk drives
--subtype: virtual optical drive subtype.
Note: Adding a Serial port is not supported in macOS virtual machines.
--device-add serial {--device <name>|--output <file>|--socket <name>
[--socket-mode <server|client>]}
Modify a serial port
--device-set <port_name> {--device <name>|--output <file>|--socket <name>
[--socket-mode <server|client>]}
port_name: the name of the port to modify (--device-set command only). To obtain the list of the available ports, use the prlctl list --info command.
--device: the number of the host computer serial port that will be used by the virtual machine.
--output: the path to the file where the output of the virtual serial port will be sent.
--socket: the name of the host computer socket to which the serial port will be connected.
--socket-mode: the socket operation mode.
--device-add net --type <shared | bridged | host-only> [--iface <name>] [--mac <addr | auto>]
[--ipadd <addr [/mask]> | --ipdel <addr[/mask]> | --dhcp <yes | no> | --dhcp6 <yes | no>]
[--gw <gw>] [--gw6 <gw>] [--nameserver <addr>] [--searchdomain <addr>]
[--configure <yes | no>] [--apply-iponly <yes | no>]
[--adapter-type <virtio | e1000 | e1000e | rtl>]
--device-set <adapter_name> --type <shared | bridged | host-only> [--iface <name>]
[--mac <addr | auto>]
[--ipadd <addr [/mask]> | --ipdel <addr[/mask]> | --dhcp <yes | no> | --dhcp6 <yes | no>]
[--gw <gw>] [--gw6 <gw>] [--nameserver <addr>] [--searchdomain <addr>]
[--configure <yes | no>] [--apply-iponly <yes | no>]
[--adapter-type <virtio | e1000 | e1000e | rtl>]
adapter_name: the name of the virtual network adapter to modify (--device-set command only). To obtain the list of the available adapters, use the prlctl list --info command.
--type: the type of the network adapter to create in the virtual machine.
--iface: the host network interface to be assigned to the bridged or host-only virtual network adapter.
--mac: the MAC address to be assigned to the virtual network adapter. If omitted, the MAC address will be automatically generated.
--ipadd: the IP address to be assigned to the network adapter in the virtual machine.
--ipdel: the IP address to be removed from the network adapter in the virtual machine.
--dhcp: specifies whether the virtual network adapter should get its IP settings through a DHCP server.
--dhcp6: specifies whether the virtual network adapter should get its IPv6 settings through a DHCP server.
--gw: the default gateway to be used by the virtual machine.
--gw6: the default IPv6 gateway to be used by the virtual machine.
--nameserver: the default DNS server to be used by the virtual machine.
--searchdomain: the default search domain to be used by the virtual machine.
--configure: if set to yes, the settings above are applied to the virtual network adapter instead of its original settings. Configuring any of the settings automatically sets this option to yes.
--apply-iponly: if set to yes, the hostname, nameserver, and search domain settings from the virtual machine configuration file are ignored.
--adapter-type: specifies the network adapter emulation type.
--device-add parallel {--device <name> | --output <file>}
Modify a parallel port
--device-set <port_name> {--device <name> | --output <file>}
port_name: the name of the port to modify (--device-set command only). To obtain the list of the available ports, use the prlctl list --info command.
--device: the parallel port number on the host computer that will be used by the virtual machine.
--output: the path to the file where the output of the virtual parallel port will be sent.
Note: Adding a sound card is not supported in macOS virtual machines.
--device-add sound --output <name> --input <name>
--ouput: the name of a physical output device to which to connect the virtual sound card.
--input: the name of the physical input device to which to connect the virtual sound card.
This command adds USB support to a virtual machine, making the USB & Bluetooth configuration options available.
--device-add usb
A shared folder is a host OS folder that can be accessed from a virtual machine.
--shf-host <on | off>
Enables or disables sharing the user-defined host OS folders with guest OS.
--shf-host-add <name> --path <path> [--mode <ro | rw>] [--shf-description <desc>]
[--enable | --disable]
Shares the host OS folder name with a virtual machine.
--shf-host-del <name>
Removes the specified folder from the list of shared folders.
--shf-host-set <name> --path <path> [--mode <ro | rw>] [--shf-description <desc>]
[--enable | --disable]
Modifies the settings of the host OS shared folder name.
--shf-host-defined <off | alldisks | home>
off: Disable sharing of folders defined by the host OS.
alldisks: Share all host OS disks with a virtual machine.
home: Share a host OS user's home directory with a virtual machine.
--shf-guest <on | off>
Enables or disables sharing of user-defined guest OS folders with the host OS.
--shf-guest-automount <on | off>
Enables or disables automatic mounting of shared guest OS folders on the desktop.
--time-sync <on | off>
Enables or disables the virtual machine time synchronization.
--disable-timezone-sync <on | off>
Enables or disables timezone synchronization. Enable this option to sync only UTC time without timezone synchronization.
--sync-vm-hostname <on | off>
Enables or disables synchronization of the virtual machine name and hostname in guest OS. Supported only for Linux guests.
--sync-ssh-ids <on | off>
Enables or disables synchronization of macOS SSH public keys with those from the guest OS "authorized_keys" file.
This feature is similar to the ssh-copy-id(1) utility. When enabled, all macOS SSH public keys are added to the guest OS "authorized_keys" file. This allows users to log in to the guest OS via SSH without having to enter the password.
The following SSH keys are synced:
- When a user creates a new SSH key pair in macOS, the public key is also added to the guest OS.
- When a user removes a public key from macOS, this key is also removed from the guest OS.
The details of the current implementation:
- Public key synchronization is currently available for Linux guests only.
- Public key synchronization works if the guest OS user has the same name in macOS or the user is the only regular user of the guest system.
The public key is synced in the following cases:
- After Parallels Tools are installed.
- After booting or rebooting the guest OS.
- After the virtual machine resumes.
- After the public key synchronization feature is enabled/disabled.
Additional information:
- If the feature is disabled, all macOS SSH public keys are removed from the guest OS.
- The "authorized_keys" file and public keys are searched only in the "~/.ssh" directory.
- SSH authorization certificates are not supported.
--show-dev-tools <on | off>
Enables or disables show developer tools in the menu.
--swipe-from-edges <on | off>
Enables or disables edge swipe gestures.
--rename-ext-disks
Renames external virtual hard drive bundles using the virtual machine name.
--name <name>
Changes the virtual machine name.
--description <desc>
Sets the virtual machine description.
--distribution <name | list>
Sets the virtual machine OS version(s) family.
--asset-id <id>
Changes the virtual machine asset ID.
--template <on | off>
Converts the virtual machine to the template and back.
--tools-autoupdate <yes | no>
Enables or disables the auto-update mode for Parallels Tools Agent.
--usedefanswers <on | off>
Enables or disables default mech answers to the questions from the virtual machine.
prlctl snapshot-list <vm_id | vm_name> [{-t,--tree] | [-i,--id <snapid>}] [-j, json]
Lists the virtual machine snapshot tree. There are three modes of snapshot listing:
If the -t, --tree option is specified, the tree is displayed using ASCII graphics.
If the -i, --id <snapid> option is specified, the specified snapshot information is displayed.
If no option is specified, the snapshot tree is displayed as a table with two columns: PARENT_SNAPSHOT_ID, SNAPSHOT_ID.
The optional -j, --json parameter produces an output in JSON format.
This section describes command used to manage virtual machine snapshots.
prlctl snapshot-switch <vm_id | vm_name> -i, --id <snapid> [--skip-resume]
Reverts the specified virtual machine to the specified snapshot. The -i, --id <snapid> parameter specifies the ID of a snapshot to revert to.
If the optional --skip-resume parameter is included, the virtual machine will not be started if it was running when the snapshot was taken.
prlctl guest-debugger <vm_id | vm_name> [--port <port>]
Allows you to connect the debugger to a running virtual machine via the specified port. The debugger must be installed on the same computer where the virtual machine is running.
This section describes various other prlctl commands.
prlctl problem-report <vm_id | vm_name>
<-d, --dump | -s, --send [--proxy [user [:password] @proxyhost [:port]]] [--no-proxy]>
Generates a problem report. If the -s, --send option is specified, the report is sent to Parallels. Otherwise, it is dumped to stdout.
-d, --dump
If included, the report is displayed on the screen. You can pipe the output to a file and then send it to the Parallels technical support.
-s, --send
If this option is included (instead of -d, --dump), the report is sent to Parallels. You can specify additional optional parameters, which are described below.
--proxy user:password@proxyhost:port
If you use a proxy server to connect to the Internet, include the --proxy parameter and specify the proxy server information. The problem report will be sent to Parallels through this proxy server.
--no-proxy
Do not use a proxy server to send the problem report. This is the default behavior, so you can include or omit this parameter.
--name <user_name>
Inserts the specified user name into the report.
--email <user_e-mail>
Inserts the specified e-mail address into the report.
--description <problem_description>
Inserts the specified free-form description into the report.
prlctl debug-dump <vm_id | vm_name>
[--name <dump_file_name>] [--path <output_directory_path>]
Creates a virtual machine dump in ELF format and saves it to a file. The resulting dump file can be opened with the Linux crash utility or (with some limitations) with the GDB debugger.
--name <dump_file_name>
Allows you to specify a dump file name. By default, the file is named memory.elf.dmp. When you create a new dump file, it replaces the previous file (if it exists). Giving it a custom name to a file solves this issue.
--path <output_directory_path>]
By default, dump files are saved to the virtual machine directory. If you want to save them to another directory, specify the directory path using the --path parameter.
Note: To create a dump, the virtual machine must be running or paused. Suspended virtual machines are not supported by this command. The command returns 0 (zero) on success and a non-zero value on failure.
The following options can be used with the prlctl set command to manage devices:
--device-add — add a new device.
--device-set — modify an existing device.
--device-del — delete (remove) a device.
--device-connect — connect a device.
--device-disconnect — disconnect a device.
Only one option can be specified in a single command.