Product documentation
Citrix Virtual Apps and Desktops
Current Release Service 2607 LTSR 2511 2507 LTSR 2503 2411 2407 2402 LTSR 2311 2203 LTSR
View PDF

Preparation

September 23, 2026
Contributed by: 
C

Before beginning an upgrade, review the following information and complete the necessary tasks.

Note:

Although upgrading VDAs occurs later in the upgrade procedure, it’s a good idea to choose an installer and review the procedure before you start the upgrade, so you know what to expect.

Pre-upgrade checklist

Complete the following tasks before you start the upgrade. Each item links to its details:

Choose an installer and interface

Use the full-product installer from the product ISO to upgrade components. You can upgrade VDAs using the full-product installer or one of the standalone VDA installers. All installers offer graphical and command-line interfaces.

For more information, see Installers.

Installation specifics: After you complete any preparation work and are ready to start the installer, the installation article shows you what you will see (if you’re using the graphical interface) or what to type (if you’re using the command-line interface).

For single-session operating systems, four different installers are available. Citrix advises using a consistent installer type throughout the entire life cycle of a Citrix VDA—including installation, upgrade, and uninstallation. For more information, see Best practices for using single-session VDA installers

When upgrading a VDA to the current release, a machine restart occurs during the upgrade process. (This requirement started with the 7.17 release.) The restart cannot be avoided. The upgrade resumes automatically after the restart (unless you specify /noresume on the command line).

Verify your Citrix licensing

For a comprehensive look at managing Citrix Licensing, see Activate, upgrade, and manage Citrix licenses.

You can use the full-product installer to upgrade the License Server. Or, you can download and upgrade the license components separately. See Upgrade.

Before upgrading, be sure your Customer Success Services / Software Maintenance / Subscription Advantage date is valid for the new product version. The date must be at least 2021.11.15.

Verify License Server compatibility

Ensure that your Citrix License Server is compatible with the new version. There are two ways to verify compatibility:

  • Before upgrading any other Citrix components, run the XenDesktopServerSetup.exe installer from the ISO layout on the machine containing a Delivery Controller. If there are any incompatibility issues, the installer reports it with recommended steps to resolve the issues.

  • From the XenDesktop Setup directory on the installation media, run the command: .\LicServVerify.exe -h <license-server-fqdn> -p 27000 -v. The display indicates whether the License Server is compatible. If the License Server is incompatible, upgrade the license server.

Update Hybrid Rights licenses

Hybrid Rights licenses are term-based subscription licenses that are provided, in addition to the cloud service subscription, when a customer transitions or trades up from a perpetual license to a cloud service subscription. You can also purchase a Hybrid Rights add-on with your DaaS subscriptions.

Hybrid Rights license with a SaaS attribute

When you upgrade to Citrix Virtual Apps and Desktops™ LTSR 2203 and later, you become eligible for capabilities not available with LTSR 1912. These capabilities include provisioning and hosting workloads in public clouds, such as Microsoft Azure, AWS EC2, and Google Cloud. Before you deploy the new license file, update your License Server to the most recent version. If you skip this prerequisite, the update blocks Citrix Virtual Apps and Desktops site upgrades and site creation.

Hybrid Rights license with no SaaS attribute

Follow these steps to get the new Hybrid Rights license with a SaaS attribute:

Note:

  • You get an email with a new license code. For more information see, Use license access code.
  • Your existing licenses are rescinded. Rescinded licenses must be deleted from License Servers followed by new license installation. For more information, see Deleting license files.

  1. Go to citrix.com Manage Licenses portal and download the new Hybrid Rights license file with cloud provisioning rights enabled (SaaS attribute). For more information, see Download licenses. The following image shows the Hybrid Rights license file with the SaaS attribute in the Increments section.

    SaaS attribute in license file

  2. Install the Hybrid Rights license file on the License Server. For more information, see Install licenses.
  3. If there is a change in license editions or model, make sure you run the broker command to set the edition and the model and then start the in-place upgrade. For more information about Broker commands, see Broker PowerShell SDK section.

For more information about public cloud support with Citrix Virtual Apps and Desktops Current Releases and Long Term Service Releases, see CTX270373.

Back up the databases

Back up the site, monitoring, and configuration logging databases. Follow the instructions in CTX135207. If any issues are discovered after the upgrade, you can restore the backup.

For information about upgrading SQL Server versions that are no longer supported, see Check the SQL Server version. (The SQL Server version check refers to the SQL Server that is used for the site, monitor, and configuration logging databases.)

Microsoft SQL Server Express LocalDB is installed automatically, for use with Local Host Cache. If you need to replace an earlier version, the new version must be SQL Server Express LocalDB 2019. For details about replacing SQL Server Express LocalDB with the new version after you upgrade the components and the site, see Replace SQL Server Express LocalDB.

Check the SQL Server version

A successful Citrix Virtual Apps and Desktops deployment requires a supported version of Microsoft SQL Server for the site, monitor, and configuration logging databases. Upgrading a Citrix deployment with a SQL Server version that’s no longer supported can result in functionality issues, and the site will be unsupported.

To learn which SQL Server versions are supported for the Citrix release you’re upgrading to, see the System requirements article for that release.

When upgrading a Controller, the Citrix installer checks the currently installed SQL Server version used for the site, monitor, and configuration logging databases.

  • If the check determines that the currently installed SQL Server version is not a supported version in the Citrix release you’re upgrading to:

    • Graphical interface: The upgrade halts with a message. Click I understand and then click Cancel to close the Citrix installer. (You cannot continue with the upgrade.)
    • Command-line interface: the command fails (even if you included the /ignore_db_check_failure option with the command).

    Upgrade the SQL Server version, and then start the Citrix upgrade again.

  • If the check cannot determine which SQL Server version is currently installed, see if your currently installed version is supported in the version you’re upgrading to (System requirements).

    • Graphical interface: The upgrade halts with a message.

      • If the currently installed SQL Server version is supported, click I understand to close the message, and then click Next to continue with the Citrix upgrade.
      • If the currently installed SQL Server version is not supported, click I understand to close the message, and then click Cancel to end the Citrix upgrade. Upgrade your SQL Server to a supported version and then start the Citrix upgrade again.

    • Command-line interface: The command fails with a message. After closing the message:

      • If the currently installed SQL Server version is supported, run the command again with the /ignore_db_check_failure option.
      • If the currently installed SQL Server version is not supported, upgrade your SQL Server to a supported version. Run the command again to start the Citrix upgrade.

Upgrade SQL Server

If you bring up new SQL Server servers and migrate the site database, then connection strings must be updated.

If the site currently uses SQL Server Express for the site database (that Citrix installed automatically during site creation):

  1. Install the latest SQL Server Express version.
  2. Detach the database.
  3. Attach the database to the new SQL Server Express.
  4. Migrate connection strings.

For more information, see Configuring connection strings and the Microsoft SQL Server product documentation.

Back up any StoreFront modifications

Before starting an upgrade, if you have modified files in C:\inetpub\wwwroot\Citrix\<StoreName>\App_Data, such as default.ica and usernamepassword.tfrm, back them up for each store. After the upgrade you can restore them to reinstate your modifications.

Remove PvD, AppDisks, and unsupported hosts

The following technologies and host types are not supported in Citrix Virtual Apps and Desktops 7 Current Release deployments:

  • Personal vDisks (PvD) for storing data next to users’ VMs in catalogs. The user personalization layer feature now handles user persistence.
  • AppDisks for managing applications used in Delivery Groups.
  • Host types: Azure Classic, CloudPlatform (the original Citrix product).

If your current deployment uses PvDs or AppDisks, or has connections to unsupported host types (for example, Microsoft Azure Classic), you can upgrade to version 2006 (or later supported versions) only after removing items that use those technologies. If your current deployment uses public cloud host connections (for example, AWS), ensure that you have Hybrid Rights License before upgrading. When the installer detects one or more of the unsupported technologies or host connections without Hybrid Rights License, the upgrade pauses or stops, and an explanatory message appears. The installer logs contain details.

To help ensure a successful upgrade, review and follow the applicable guidance for removing the unsupported items.

Even if you did not use PvD or AppDisks in your deployment, related MSIs might have been included in an earlier VDA installation or upgrade. Before you can upgrade your VDAs to version 2006 (or a later supported version), you must remove that software, even if you never used it. When using the graphical interface, that removal can be done for you, or you can include removal options when using the CLI. For details, see Remove PvD or AppDisks components from VDAs.

Remove PvD

A deployment upgrade cannot succeed until you remove all machines that are configured to use PvD. This removal affects catalogs and Delivery Groups.

To remove PvD from groups and catalogs:

  1. From Studio, if a Delivery Group contains machines from a catalog that uses PvD, remove those machines from the group.
  2. From Studio, delete all catalogs containing machines that use PvD.

VDA upgrades: The deployment upgrade does not detect whether VDAs have the AppDisk or PvD components installed. However, the VDA installers do. For details, see Remove PvD or AppDisks components from VDAs.

If you plan to use App Layering instead of PvD, see Migrating PvD to App Layering for information about moving data.

Remove AppDisks

A deployment upgrade cannot proceed until you remove AppDisks from all Delivery Groups that use them, and then remove the AppDisks themselves.

  1. Select Delivery Groups in the Studio navigation pane.
  2. Select a group and then click Manage AppDisks in the Action pane.
  3. Click the action that removes the AppDisk from the group.
  4. Repeat steps 2 and 3 for each Delivery Group that uses AppDisks.
  5. Select AppDisks in the Studio navigation pane.
  6. Select an AppDisk and click the action that deletes the AppDisk.
  7. Repeat steps 5 and 6 for each AppDisk.

VDA upgrades: The deployment upgrade does not detect whether VDAs have the AppDisk or PvD components installed. However, the VDA installers do. For details, see Remove PvD or AppDisks components from VDAs.

Remove unsupported host items

A deployment upgrade to version 2006 (or later supported version) cannot proceed if the site has connections to unsupported host types, such as Citrix CloudPlatform or Microsoft Azure Classic. Complete the following tasks before attempting an upgrade.

From Studio:

Remove PvD or AppDisks components from VDAs

If the components that enable PvD and AppDisks technologies are installed on a VDA, that VDA cannot be upgraded until those components are removed. This restriction applies even if you never used PvD or AppDisks.

Note:

When upgrading to version 1912, you had to uninstall the current VDA and then install the new VDA. In this version, you’re asked if you want Citrix to remove the component and then continue the upgrade.

The AppDisk and PvD components might have been installed in earlier VDA versions, even if you never used those technologies:

  • Graphical interface: In the VDA installers, the Additional Components page contained the Citrix AppDisk / Personal vDisk option. The 7.15 LTSR and earlier 7.x releases enabled this option by default. So, if you accepted the defaults (or explicitly enabled the option in any release that offered it), that component was installed.
  • CLI: Specifying the /baseimage option installed the component.

Remove the components

If the VDA installer does not detect the AppDisks or PvD components in the currently installed VDA, the upgrade proceeds as usual.

If the installer detects AppDisks or PvD components in the currently installed VDA:

  • Graphical interface: The upgrade pauses. A message asks if you want the unsupported components removed automatically. If you click OK, the components are removed automatically and the upgrade proceeds.

  • CLI: To avoid command failure, include the following options in the command:

    • /remove_appdisk_ack
    • /remove_pvd_ack

Continue using PvD on earlier Windows versions

If you want to continue using PvD on your Windows 10 (1607 and earlier, without updates) machines, VDA 7.15 LTSR is the latest supported version.

Note:

Can I use Personal vDisk with Windows 7 desktops in XenApp and XenDesktop 7.15 LTSR?

Citrix excluded Personal vDisk (PvD) from XenApp and XenDesktop 7.6 LTSR which was announced in January 2016. Additionally, Citrix has announced the deprecation of the PvD technology and recommends that customers start using Citrix App Layering going forward. Citrix App Layering (version 4.4 and later) is a compatible component of XenApp and XenDesktop 7.15 LTSR. However, to help customers with existing PvD deployments on Windows 7 migrate to Citrix App Layering technology, Citrix has decided to provide limited time support for PvD deployments for Windows 7 desktops through XenApp and XenDesktop 7.15 LTSR Cumulative Updates (CUs) until Jan 14, 2020. The PvD component will be removed from LTSR CUs and not supported after Jan 14, 2020. Also, use of PvD for Windows 7 beyond Jan 14, 2020 will render LTSR sites non-compliant. Also, PvD for Windows 10 remains excluded from 7.15 LTSR. Therefore, customers must not use it with their 7.15 LTSR sites.

Close applications and consoles

Before starting an upgrade, close all programs that might potentially cause file locks, including administration consoles and PowerShell sessions.

Restarting the machine ensures that any file locks are cleared, and that there are no Windows updates pending.

Before starting an upgrade, stop and disable any third-party monitoring agent services.

Verify your permissions

In addition to being a domain user, you must be a local administrator on the machines where you are upgrading product components.

The site database and the site can be upgraded automatically or manually. For an automatic database upgrade, the Studio user’s permissions must include the ability to update the SQL Server database schema (for example, the db_securityadmin or db_owner database role). For details, see Databases.

If the Studio user does not have those permissions, initiating a manual database upgrade generates scripts. The Studio user runs some of the scripts from Studio. The database administrator runs other scripts, using a tool such as SQL Server Management Studio.

Run preliminary site tests

When you upgrade Delivery Controllers and a site, preliminary site tests run before the actual upgrade begins. These tests verify:

  • The site database can be reached and has been backed up
  • Connections to essential Citrix services are working correctly
  • The Citrix License Server address is available
  • The configuration logging database can be reached
  • Ensure you have Hybrid Rights License if you want to add public cloud host connections (for example, AWS). Otherwise, the preliminary site test pauses or stops, and an explanatory message appears.

After the tests run, you can view a report of the results. You can then fix any issues that were detected, and run the tests again. Failure to run the preliminary site tests and then resolve any issues can impact how your site works.

The report containing the test results is an HTML file (PreliminarySiteTestResult.html) in the same directory as the installation logs. That file is created if it does not exist. If the file exists, its content is overwritten.

Run the tests

  • When you’re using the installer’s graphical interface to upgrade, the wizard includes a page where you can start the tests and then display the report. After the tests run and you have viewed the report and resolved any issues that were found, you can rerun the tests. When the tests complete successfully, click Next to continue with the wizard.
  • When you’re using the command-line interface to upgrade, the tests run automatically. By default, if a test fails, the upgrade is not performed. After you view the report and resolve issues, rerun the command.

Citrix recommends always running the preliminary site tests and then resolving any issues before you continue the Controller and site upgrade. The potential benefit is well worth the few moments to run the tests. However, you can override this recommended action.

  • When upgrading with the graphical interface, you can choose to skip the tests and continue with the upgrade.
  • When upgrading from the command line, you cannot skip the tests. By default, a failed site test causes the installer to fail, without performing the upgrade. Usually, if you include the /ignore_site_test_failure option, any test failures are ignored and the upgrade proceeds. (See Check the SQL Server version for exceptions.)

Upgrade multiple Controllers

When you start an upgrade on one Controller, and then start an upgrade of another Controller in the same site (before the first upgrade completes):

  • If the preliminary site tests are completed on the first Controller, the preliminary site tests page does not appear in the wizard on the other Controller.
  • If the tests on the first Controller are ongoing when you start the upgrade on the other Controller, the site tests page appears in the wizard on the other Controller. However, if the tests on the first Controller finish, only the test results from the first Controller are retained.

Resolve test failures unrelated to site health

  • If the preliminary site tests fail due to insufficient memory, make more memory available and then rerun the tests.
  • If you have permission to upgrade, but not run site tests, the preliminary site tests fail. To resolve this, rerun the installer with a user account that has permission to run the tests.

Complete other preparation tasks

  • Back up templates and upgrade hypervisors, if needed
  • Complete any other preparation tasks dictated by your business continuity plan.
Preparation
September 23, 2026
Contributed by: 
C
September 23, 2026
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.