We frequently hear from customers that many Amazon WorkSpaces deployments run on operating systems (OS) that are near end-of-life. These older environments, paired with legacy streaming protocols, limit access to the latest features, security updates, and long-term support.

Modernization is more than a protocol change. It is an opportunity to upgrade the OS, adopt Amazon DCV for optimal performance, and build automation to keep your fleet current.

In this post, you learn how to:

• Audit your current WorkSpaces deployment to find legacy OS and streaming protocols that need upgrades
• Plan a migration strategy that addresses OS modernization and protocol modification together, and build custom DCV bundles
• Migrate WorkSpaces on legacy OS to a modern OS with DCV by using the Amazon WorkSpaces console or the WorkSpaces Migration Tool
• Perform in-place protocol modifications for WorkSpaces on a supported OS and automate bulk migrations by using the WorkSpaces Migration Tool

Overview

Amazon DCV is the next-generation streaming protocol for WorkSpaces. It supports Windows 11, Windows Server 2022, Windows Server 2025, Ubuntu, RHEL, and Rocky Linux. DCV provides stronger security (certificate-based authentication, WebAuthn), optimal performance even at higher latency, multi-monitor support, smart card redirection, and webcam support.

Amazon WorkSpaces Personal includes migration features that simplify the transition. The Migrate WorkSpace operation combines an OS upgrade and protocol change into one step. The console supports single migrations, while the WorkSpaces Migration Tool (available on GitHub as a sample) automates bulk operations across your fleet with CSV-driven workflows, state validation, and detailed status tracking.

Your migration path depends on the current OS running on your WorkSpaces:

Prerequisites

• AWS Management Console access with WorkSpaces Administrator permissions or the AWS CLI v2 configured along with the JQ JSON processor for the WorkSpaces Migration Tool.
• DCV-compatible endpoint devices and WorkSpaces client 5.x or later.
• For protocol modification the WorkSpace must be in Available state. For bundle migration, the WorkSpace must be in Available, Stopped, or Error state.
• TCP/UDP 4195 or 443 on your network allow list for DCV traffic.
• DCV-specific Group Policy Administrative Template configured in Active Directory (PCoIP GPO settings do not carry over).

Phase 1: Audit your WorkSpaces deployment

Find which WorkSpaces use PCoIP, find their OS version, and locate available target bundles.

To audit manually, filter WorkSpaces by Protocol in the Amazon WorkSpaces console and review the Bundle column. For larger deployments, use the WorkSpaces Migration Tool’s inventory phase instead.

Run the inventory script against your region or use the multi-region wrapper to audit all regions at once. The tool:

• Queries every WorkSpace and classifies it by OS category (Legacy, Supported, or Unknown) based on bundle-name pattern matching
• Outputs an inventory CSV with one row per WorkSpace and a suggested action (MIGRATE, MODIFY_PROTOCOL, or REVIEW)
• Generates a companion CSV listing of all available DCV bundles in the region, with volume sizes and compute tiers. Use this to select the right migration targets.

Phase 2: Plan your migration

With your audit complete, plan your migration in two steps. Address legacy OS WorkSpaces first (Step 1), then perform in-place protocol modifications on supported OS WorkSpaces (Step 2).

Step 1: Legacy OS modernization

For WorkSpaces on legacy OS (Windows Server 2016, Windows 10), use the Migrate WorkSpace API:

• Creates a new WorkSpace from a modern OS + DCV bundle and move user data (D: drive)
• Preserves the user assignment and delete the old WorkSpace
• Perform single migrations from the console, or use the WorkSpaces Migration Tool for batch operations
• In the tool’s CSV, set the ACTION column to MIGRATE and specify the TARGET_BUNDLE_ID from the available DCV bundles list

If no existing DCV bundle matches your requirements, create a custom bundle. For detailed steps, see Create a custom WorkSpaces image and bundle in the Administration Guide.

Step 2: In-place protocol modification

For WorkSpaces on a supported OS (Windows Server 2019, 2022), use the Modify WorkSpace Protocol feature:

• Modifies the protocol to DCV in-place with no rebuild required
• User data, applications, and settings stay the same
• Modify individual WorkSpaces from the console, or use the WorkSpaces Migration Tool for fleet-wide changes

In the migration tool’s CSV, set the ACTION column to MODIFY_PROTOCOL

Select your target bundle

When choosing a target bundle, ensure it uses DCV with a supported OS (Windows Server 2022, 2025, or Windows 11). Match or upgrade the compute tier and verify that target volume sizes are equal to or larger than the source.

Network and client requirements

Ensure TCP/UDP 4195 or 443 is open on corporate firewalls (DCV uses TCP/UDP 4195 or 443, replacing PCoIP’s TCP/UDP 4172). All end-user devices must run WorkSpaces client 5.x or later, or be enabled to consume the Web Access Client with supported configuration (see WorkSpaces Web Access documentation). Plan central client updates (SCCM, Intune) ahead of the migration.

Rollout and communication

Notify users in advance of migration windows. Remind Step 1 users that C: drive applications require reinstallation. Start with a pilot group of 5–10 WorkSpaces, validate performance under DCV using organizational user acceptance testing procedures, then expand in waves.

For related best practices, see the AWS Whitepaper on Development and Test. Some of these practices apply to migration planning.

Phase 3: Migrate WorkSpaces on legacy OS

In this step, you migrate WorkSpaces on legacy OS to a new bundle with a modern OS and DCV.

The Migrate WorkSpace API creates a new WorkSpace from your target bundle, copies user data from the source, and deletes the old WorkSpace.

Important considerations

Before you begin, review these requirements:

• The source WorkSpace must be in AVAILABLE, STOPPED, or ERROR state
• The migration copies user data from D:\Users\%USERNAME% to the new instance.
• Applications on the system volume (C: drive) do not migrate—you must reinstall them or include them in the target bundle image.

Using the console or the Migration Tool

To migrate a single WorkSpace from the console, select it, choose Actions > Migrate WorkSpace, pick your target bundle, and confirm. The WorkSpace enters PENDING state until the migration is complete.

For bulk migrations, use the WorkSpaces Migration Tool:

• Review and approve your inventory CSV (set ACTION to MIGRATE and provide TARGET_BUNDLE_ID for each row)
• Run the execute script; the tool validates each WorkSpace’s state before calling the API
• Runs operations in batches of 25 with pauses between them and retries on throttled requests
• Use –dry-run first to preview every command without executing
• The tool generates an execution report CSV with the outcome of each operation

After migration completes, instruct users to log in to their new WorkSpace and verify their data is intact.

Phase 4: Modify protocol for supported OS WorkSpaces

For WorkSpaces on a supported OS (Windows Server 2019, 2022), modify the protocol in-place. User data, applications, and settings stay the same. The WorkSpace must be in AVAILABLE or STOPPED state.

Modifying protocol to DCV

From the console, select the WorkSpace, choose Actions > Modify Protocol, and choose Start. The WorkSpace transitions to Modifying Protocol state, then returns to AVAILABLE state.

For fleet-wide modifications, use the WorkSpaces Migration Tool with ACTION set to MODIFY_PROTOCOL in your approved CSV:

• The tool validates state before each call and processes modifications in batches
• If a modification fails (State shows UNHEALTHY), restore the WorkSpace from the console (Actions > Restore WorkSpace)
• Investigate common causes: mismatched bundle types, blocked DCV ports, or incomplete updates

Validation and testing

After you complete your migrations, validate that all WorkSpaces use DCV and that end users connect successfully:

• Re-run the audit from Phase 1. Filter by Protocol in the console or run the Migration Tool’s verify command to check status across all regions in a single pass.
• Have users connect with the latest WorkSpaces client—DCV requires client version 5.x or later (see Identifying Amazon WorkSpaces clients approaching end-of-life).
• Check that DCV ports (TCP/UDP 4195 or 443) are open from all client locations.
• For legacy OS WorkSpaces from Phase 3, confirm user data integrity.

To confirm no PCoIP WorkSpaces remain, filter by Protocol in the console or run the Migration Tool’s verify command. For multi-region verification, the tool checks status across all active regions in a single pass and reports completion percentage.

Automating at scale

The sample WorkSpaces Migration Tool (available on GitHub) manages end-to-end migrations for fleets of any size. It is a CLI tool that runs in Bash 4+ (Linux, macOS, CloudShell or WSL).

The tool implements a three-phase, CSV-driven workflow:

1. Inventory — Run the inventory script (01-inventory.sh) for a single region, or use the multi-region wrapper to audit all regions at once. The tool queries every WorkSpace, classifies each by OS using the API’s OperatingSystemName field (with bundle-name fallback). It lists all available DCV bundles with volume sizes to help you pick targets.
2. Review — Open the CSV and edit the ACTION column. Set MIGRATE (with a TARGET_BUNDLE_ID) for legacy OS WorkSpaces, MODIFY_PROTOCOL for supported OS WorkSpaces, or SKIP to exclude a WorkSpace. Rows marked REVIEW need manual classification when the tool cannot identify the OS from the bundle name.
3. Run — Run the execute script (02-execute.sh) with your approved CSV. The tool checks each WorkSpace’s state before every API call. It processes batches of 25 (with a 5-second pause between them) and retries throttled requests with increasing delays. Use –dry-run first to preview commands without running them.

After execution, run the verify script (03-verify.sh) to confirm all WorkSpaces report DCV as their protocol. The tool outputs results and a completion percentage.

For multi-region deployments, the wrapper adds more commands: discover (finds active regions via SSM parameters), inventory, execute, and verify. Output is sorted by region in a structured directory.

Key safety features:

• CSV-gated execution (no changes without explicit approval)
• State validation and dry-run mode
• Confirmation prompts before destructive actions
• Batch throttling and continue-on-error handling
• Detailed execution report for audit purposes

First test in non-production environments, then run in small batches. If you plan a large-scale migration, verify your AWS Support plan covers your migration needs and engage your AWS account team or AWS Support for assistance.

Conclusion

When you combine OS upgrades with the move to Amazon DCV, you unlock the latest features and prepare your environment for Windows Server 2025 and Windows 11.

Start your migration plan now. Use the WorkSpaces Migration Tool on GitHub to automate and scale your efforts. For more information, see the Amazon WorkSpaces Administration Guide and the Amazon DCV documentation.

About the authors:

	Phil Persson is a WorldWide Principal Solutions Architect for Applied AI Solutions and Amazon WorkSpaces. Phil has been with AWS since December 2012 where he was a founding member of AWS Premium Support in the Sydney Region and then a Technical Account Manager for AWS Enterprise Support
	Saumya Vij is a Senior Product Manager for Amazon WorkSpaces. He brings over a decade of experience across hardware and software to help drive the product’s vision and deliver solutions that meet the evolving needs of AWS End User Computing customers.
	Asriel Agronin is a Senior End User Computing Solutions Architect. He works with Federal customers designing and architecting EUC solutions on AWS. He has been with AWS since 2017. In his free time, you can find Asriel scuba diving, traveling, or playing chess.