1 of 100

PD_Dev_Guide_En

Introduction

This guide contains information about all functions of Parallels Desktop for Macs that are or can be related to software development and testing.

Parallels Desktop in Software Development

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/Enterprise Editions unless explicitly stated otherwise.

Optimizing Your Virtual Machine for Software Development

When creating a virtual machine in Parallels Desktop Pro or Business/Enterprise 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.

Download Pre-Configured Virtual Machines

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.

Downloading Parallels Free Systems

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:

Software Development-specific Functions of Parallels Desktop

Generating a Core Dump

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 here.

Debugging a Virtual Machine Using KDBG Protocol

By default, Parallels Desktop for Mac supports GDB for debugging virtual machines. However, there is a way to enable KDBG support and allow the use of clients like WinDbg or KD.

Note: This implementation enables debugging at the virtual machine level, regardless of what OS it is running. However, since KDBG is largely Windows-specific, some of the functionality may not be available because the kernel information is unknown and/or encrypted (e.g., kernel debug block).

Known Limitations and Unsupported Commands

The current implementation of KDBG support in Parallels Desktop for Mac can only be used as a raw debugger, with little to no connection with the kernel itself.

The following commands are not supported or have limited support for now:

Software breakpoints (not supported).
Read and write I/O ports (not supported).
Read and write bus data (not supported).
Reboot and bugchecks (these will force a disconnection)

Enabling KDBG Support in Parallels Desktop

To enable KDBG support, you have to manually edit the configuration file for the target machine:

In the Control Center, right-click on the target machine and select Show in Finder.
Right-click on the virtual machine's .pvm file and select Show Package Contents.
Right-click on the config.pvs file, select Open With, and choose your preferred text editor.

Here are the system flags that you may want to use:

Flag

Description

Here is an example of a configuation:

This configuration implies a host located at 192.168.1.205 using a pre-shared encryption key aaaaaaaaaaaa.bbbbbbbbbbbb.cccccccccccc.dddddddddddd to debug a target at 192.168.1.189 via port 50000.

You may forgo explicitly specifying the host address, in which case you will have to specify the target's address in the debugging software that you use, prompting the host to send a special "poke" packet first to help the target identify it.

Following a reboot, the target machine will start sending packets to the host, ready to be debugged.

What Happens When the Connection Gets Interrupted

KDBG protocol doesn’t have a mechanism to terminate a connection, so the Parallels implementation forces the disconnect after 16 bad packets, or no packets at all for 10 minutes.

Since all traffic is encrypted using a data channel/session key, attemting to reestablish a dropped connection is not feasible.

Since UDP is not the most reliable protocol, the data channel may sometimes get out of sync, in which case the debugger appears to freeze. When that happens, the only way to fix it is to wait for the 10 minutes for a forced disconnection.

Most Common Commands

These are the most common commands that you can use and that are supported:

r - read/write registers. Ex.: “r”, “r x0 = 0”
u - unassemble. Ex.: “u pc”
d - display memory. Ex.: “d sp”, “db sp” (display as bytes), “dw sp” (display as words)
e - edit memory. Ex.: “eb sp ff”, “ew x0 1234”

Using VM Names as DNS Names

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:

10.211.55.3     windows-11.shared windows-11 #prl_hostonly shared

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:

ping windows-11.shared

, 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.

Starting a Debugging Session

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.

Establishing a Serial Connection over TCP

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.

Using Rosetta to Run x86-64 Linux Software on Apple Silicon Macs

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.

Quick Setup

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 .

Resolving Guest OS DNS Requests Using etc/hosts

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:

1.2.3.5         testh

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.

Changing the Virtual Screen Resolution on the Fly

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 . 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.

Nested Virtualization Support

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.

Simulating Adverse Network Connectivity Conditions

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.

DevOps Service

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.

Licensing

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.

Architecture

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.

Installation and Configuration

To install and configure the DevOps service, follow the dedicated guide .

Integrations and Plugins

This section includes information on various integrations that improve your development-related workflows that involve running virtual machines on Parallels Desktop for Mac.

Integration with Chef/Ohai

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:

"virtualization": {
  "systems": {
    "parallels": "host"
  },
  "system": "parallels",
  "role": "host"

And the following in the guest system:

"virtualization": {
    "systems": {
      "parallels": "guest"
    },
    "system": "parallels",
    "role": "guest"
 
}

Integration with Packer

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 .

Visual Studio Code Extension

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 .

Integration with Terraform

For the latest version of Parallels Terraform integration, follow this link.

Integration with Vagrant

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:

$ vagrant plugin install vagrant-parallels

You can set up your Vagrant-managed virtual machine by following this guide.

Command-Line Interface Utility

In Pro and Business/Enterprise 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.

Manage Parallels Desktop from CLI

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.

Display Parallels Desktop Information

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.

License Management

This section describes Parallels Desktop license management tasks.

Sign into Parallels Account

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

Install a Parallels Desktop License

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's name.

-c, --company <name>

The license company name.

--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 .

Update a License

prlsrvctl update-license

Updates the current Parallels Desktop license.

Deactivate a License

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.

Parallels Desktop Preferences

prlsrvctl set

The prlsrvctl set command is used to modify Parallels Desktop preferences. The available parameters and options are described below.

Parameters

--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.

User List and Virtual Machine Location

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.

Virtual Network Information and Settings

prlsrvctl net info <vnetwork_id>

Displays a detailed information about the specified virtual network.

prlsrvctl net list [-j, --json]

Lists existing virtual networks.

Changing Virtual Network Settings

USB Devices

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.

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.

Report a Problem

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.

Shut Down Parallels Desktop

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.

Error Handling

The prlsrvctl utility returns 0 on success or an error code on failure.

Manage Virtual Machines from CLI

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.

General Virtual Machine Management

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.

List Virtual Machines

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.

Delete a Virtual Machine

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.

Register/Unregister a Virtual Machine

Registering a Virtual Machine

prlctl register <path>

Registers a virtual machine in Parallels Desktop. The <path> parameter specifies a path to the virtual machine file.

Clone a Virtual Machine

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.

Optional Parameters

--template

Make the new virtual machine a template.

Convert a Virtual Machine

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.

Move Virtual Machine Files

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.

Install Parallels Tools

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.

Reclaim Disk Space

prlctl reclaim-disk <vm_id> [--estimate] [--allow-shutdown] [--json]

Optimizes the virtual machine's disk file to reduce the disk space it occupies. Use this command when you have just deleted a large amount of files and need to free up space urgently; otherwise, normal procedures (e.g., TRIM on Windows machines) will suffice.

To proceed with this operation, the virtual machine must be shut down first. Applying the --allow-shutdown parameter will shut down a running virtual machine before the reclaim operation is performed.

When used with the --estimate parameter, will only provide the estimated size but will not actually reclaim any space. Adding --json in conjunction will change the output to JSON.

Log into a Virtual Machine

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.

Optional Parameters

--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.

Execute a Command in a Virtual Machine

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.

Optional Parameters

--current-user or --user <user_name>

Include the --current-user

Send a Keyboard Event to a Virtual Machine

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 . See examples .

prlctl send-key-event <VM ID> -j,--json

Sends a sequence of keyboard events by reading JSON input from stdin. An example of the format is:

Query the Virtual Machine Status

prlctl status <vm_id | vm_name>

Displays the status of the specified virtual machine.

Power Operations

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.

Capture a Screen Area

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.

Encrypt/Decrypt a Virtual Machine

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.

Archive/Unarchive a Virtual Machine

prlctl archive <vm_id | vm_name>

Archives the specified virtual machine bundle.

prlctl unarchive <vm_id | vm_name>

Unarchives the specified virtual machine bundle.

Set Password Protection

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.

Virtual Machine Configuration Tasks

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.

CPU and Memory Parameters

--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).

Boot Order Parameters

--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>

Video Parameters

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.

Mouse & Keyboard Parameters

--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.

Virtual Printer Parameters

--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.

USB Parameters

--auto-share-camera <on | off>

Enables or disables automatic Web camera sharing.

--support-usb30 <on | off>

Enables or disables USB 3.0 support.

Startup & Shutdown Parameters

--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.

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.

Optimization Parameters

--faster-vm <on | off>

Sets the performance mode: faster virtual machine or faster host.

--adaptive-hypervisor <on | off>

Enables or disables the adaptive hypervisor.

--disable-winlogo <on | off>

Enables or disables the Windows logo.

--auto-compress <on | off>

Enables or disables automatic compression of virtual disks.

Sharing Parameters

--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.

Coherence Parameters

--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.

Expiration Date Parameters

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.

Device Management

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.

Common Options

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.

Adding/Modifying a Device

The general syntax for adding a device is as follows:

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.

Physical Hard Drive

Connect a Physical Drive

--device-add hdd --device <real_name> [--iface <ide | scsi | sata>] [--passthr <yes | no>]

[--position <n>] [--subtype <buslogic | lsi-spi |

Virtual Optical Drive

Adding an Optical Drive

Note: Adding virtual optical drives is not supported in macOS virtual machines.

--device-add cdrom [--image <name>] [--iface

Physical Optical Drive

Connecting a Physical Optical Drive

--device-add cdrom --device <name> [--iface <ide | scsi | sata>] [--passthr <yes | no>]

[--position <n>] [--subtype <buslogic | lsi-spi | lsi-sas>]

Parameters

--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.

Virtual Floppy Drive

Adding a Virtual FDD

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.

Physical Floppy Drive

Congratulations on keeping such hardware in working order.

Connecting a Physical FDD

-device-add fdd [--device <real_name>]

Virtual Serial Port

Adding a Serial Port

Note: Adding a Serial port is not supported in macOS virtual machines.

--device-add serial {--device <name>|--output <

Virtual Parallel Port

Adding a Parallel Port

--device-add parallel {--device <name> | --output <file>}

Modify a parallel port

--device-set <port_name> {--device <name> | --output <file>}

Parameters

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.

Virtual Sound Card

Adding a Sound Card

Note: Adding a sound card is not supported in macOS virtual machines.

--device-add sound --output <name> --input <name>

Adding USB Support

This command adds USB support to a virtual machine, making the USB & Bluetooth configuration options available.

--device-add usb

Shared Folders

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

Advanced Settings

--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.

--keystroke-forwarding <on | off>

Allows limited keystroke forwarding from the virtual machine to the host Mac apps to enable specific enterprise software workflows.

Miscellaneous

--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.

--tpm <on

Snapshot Management

This section describes command used to manage virtual machine snapshots.

Taking a Virtual Machine Snapshot

prlctl snapshot <vm_id | vm_name>

Creates a virtual machine snapshot.

Optional Parameters

-n, --name <name>

A snapshot name. If omitted, a default name will be used.

-d, --description <desc>

A snapshot description.

Deleting a Snapshot

prlctl snapshot-delete <vm_id | vm_name> -i, --id <snapid>

Deletes a virtual machine snapshot. The -i, --id <snapid> parameter specifies the ID of the snapshot to delete.

Optional Parameters

-c, --children

Listing Snapshots

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.

Reverting to a Snapshot

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.

Miscellaneous

This section describes various other prlctl commands.

Generating a Problem Report

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.

Parameters

-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.

Optional Parameters

--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.

Using Guest Debugger

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.

Creating a VM Dump

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.

Optional Parameters

Monitoring VM events

prlctl monitor-events

[<vm_id | vm_name>] [--utc] [--json]

Lists events from a specified virtual machine, or, if a virtual machine name/ID is not provided, from all registered virtual machines. The default time in the timestamps is local time.

Optional Parameters

--utc

Prints the time stamp in UTC instead of local time (which is default).

Virtual Machine Disk Optimization

prl_disk_tool is a standalone utility (included with Parallels Desktop) used to optimize Parallels virtual machine disk space.

Parameters

prl_disk_tool compact [--buildmap] -hdd <disk_name> [--force] [-comm <memory_name>]

prl_disk_tool compact i,info --hdd <disk_name> [comm <memory_name>]

The prl_disk_tool compact command removes all empty blocks from expanding Parallels virtual drives and reduces the space they occupy on your host machine. Compacting is performed by scanning file systems for unused clusters and cleaning the corresponding disk blocks. The supported file systems are NTFS, FAT16/32, ext2/ext3. You can also try to compact disks with unsupported file system types using the --buildmap option.

Error Handling

The prlctl utility returns 0 on success or an error code on failure.

Security Parameters

Require an administrator password to perform a corresponding action. Use --allow-to-confirm to make the system ask for username and password.

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).

Create a Virtual Machine

Syntax 1

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.

Optional parameters

--dst

A path to the directory where the virtual machine files will be stored. If omitted, the default location will be used.

Syntax 2

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 11 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.

Syntax 3

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.

Creating a x86_64 Virtual Machine on Apple Silicon Macs

Starting from Parallels Desktop for Mac version 20.2.0, it has become possible to create x86_64 virtual machines on Apple silicon Macs in emulation mode. To create one, download an ISO installation image of an x86_64 operating system and execute the following three commands in macOS Terminal:

For the possible <distro> values, execute the following command:

prlctl create test -d help

The value for Windows 10 is <win-10>.

Consult for the latest list of supported operating systems.

Creating a macOS Virtual Machine

To create a macOS virtual machine, a .ipsw file with a 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 .

Creating a macOS Virtual Machine with a Customized Virtual Hard Drive Size

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 an .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> e.g., prlctl set "macOS15.5_test" --device-add hdd

For setting additional parameters like RAM size or the number of virtual CPUs, refer to of the guide.

Creating a macOS Virtual Machine in Parallels Desktop Version 18 and Earlier

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

Note: In this process, once your macOS virtual machine is created, you won't be able to change the size of its virtual hard drive.

Virtual Network Adapter

Adding a Network Adapter

--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>]

Modifying a Network Adapter

--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>]

Applying a Network Conditioner

Imitates adverse network conditions for testing purposes. Read more .

--network-conditioner [--enable | disable]

--network-conditioner [--inbound-bandwidth <value_in_kbps>] [--inbound-packet-loss <value_in_%>] [-- inbound-delay <value_in_ms>] [--outbound-bandwidth <value_in_kbps>] [--outbound-packet-loss <value_in_%>] [-- outbound-delay <value_in_ms>]

To check the current status of the network conditioner, use the prlctl list -i command and look for the respective parameter in the Network section.

Parameters

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.