--- title: Upgrading a PingAccess standalone version using the upgrade utility description: Upgrade a standalone PingAccess deployment to a newer version using the upgrade utility. component: pingaccess version: 8.2 page_id: pingaccess:upgrading_pingaccess:pa_upgrading_a_pa_standalone_version_using_the_upgrade_utility canonical_url: https://docs.pingidentity.com/pingaccess/9.1/upgrading_pingaccess/pa_upgrading_a_pa_standalone_version_using_the_upgrade_utility.html llms_txt: https://docs.pingidentity.com/pingaccess/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: July 16, 2026 superseded_by: https://docs.pingidentity.com/pingaccess/9.1/upgrading_pingaccess/pa_upgrading_a_pa_standalone_version_using_the_upgrade_utility.html section_ids: before-you-begin: Before you begin steps: Steps choose-from: Choose from: example: Example: next-steps: Next steps pingaccess-standalone-upgrade-parameters: PingAccess standalone upgrade parameters environment-variables: Environment variables java-virtual-machine-jvm-memory-options: Java virtual machine (JVM) memory options example-2: Example --- # Upgrading a PingAccess standalone version using the upgrade utility Upgrade a standalone PingAccess deployment to a newer version. Use the PingAccess upgrade utility to upgrade from your current environment version (the *source version*) to the most recent version (the *target version*). The upgrade utility starts an instance of PingAccess with an administrative listener on port 9001. You can change this port number using the `upgrade.bat` or `upgrade.sh` `-p` parameter, but this port configuration is only used for the upgrade. The upgraded server uses the port configured in the `run.properties` file after the upgrade is complete. | | | | - | --------------------------------------------------------------------------------- | | | During the upgrade, don't make any changes to the running PingAccess environment. | Any warnings or errors are recorded in `log/upgrade.log`, as well as on screen while the utility is running. The upgrade uses the following exit codes: * 0 Indicates a successful upgrade. * 1 Indicates the upgrade failed. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you're upgrading from PingAccess 4.3 or earlier and your installation uses custom plugins, you must:* Rebuild them using the SDK version included in PingAccess 5.0 or later. * Run the upgrade utility manually with the new `-i` command-line option to specify a directory containing only the custom plugin JAR files.Learn more about migrating your custom plugins in the [PingAccess Add-On SDK for Java migration guide](../agents_and_integrations/pa_add_on_sdk_for_java_migration_guide.html). | ## Before you begin * Create a backup of your existing PingAccess configuration. If the upgrade fails, restore your environment from this backup. * If you're using PingAccess 6.2 or earlier, upgrade to PingAccess 6.3 before upgrading to a more recent version. * Review the release notes for every version between the source and target version. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | PingAccess 5.0 contains potentially breaking changes to the Software Development Kit (SDK) *(tooltip: \
\

A set of tools that allows a developer to build a custom application that integrates with or connects to a platform or service.\

\
)* for Java, Groovy scripts, and the admin API. Learn more about these changes and actions administrators might need to take in [Upgrade considerations](pa_upgrade_considerations.html) and the [PingAccess 5.0](https://cdn-docs.pingidentity.com/archive/pdf/pingaccess/pingaccess-50.pdf#page=263) release notes. | * Make sure that you have: * The PingAccess distribution `.zip` file. * Your new PingAccess license file, if you plan to switch to a new license file. * Sign-on access to the PingAccess host, because the utility is run on the host. * Administrator credentials for the running PingAccess instance. * Verify the following: * Basic authentication is configured and enabled for the admin API of the source PingAccess instance. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You might need to enable basic authentication if you have limited access permissions to OAuth because of your configured role. Learn more in [Configuring API authentication](../pingaccess_user_interface_reference_guide/pa_configuring_api_authn.html). | * You're using the same account normally used to run PingAccess. * The PingAccess host is running. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you've set `security.overridePropertiesFile=false` in `$JAVA_HOME/jre/lib/java.security`, the upgrade utility might fail because the PingAccess upgrade utility uses an override to enable deprecated ciphers and protocols during the upgrade process. | ## Steps 1. Copy the `.zip` file for the new PingAccess version to the PingAccess host and extract it. 2. Go to the new version's `/upgrade/bin` directory. 3. Run the PingAccess upgrade utility: ### Choose from: * On Windows: `upgrade.bat [-p ] [-i ] [-j ] [-l ] [-s | --silent] ` * On Linux: `./upgrade.sh [-p ] [-i ] [-j ] [-l ] [-s | --silent] ` ### Example: For example: `./upgrade.sh -p 9002 -i MyJARDir pingaccess-5.3` ## Next steps Review [Performing post-upgrade tasks](pa_performing_post_upgrade_tasks.html). ## PingAccess standalone upgrade parameters The command-line parameters are the same regardless of the platform and are defined in the following table. | Parameter | Value description | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | -p *\* | Optional port to be used by the temporary PingAccess instance run during the upgrade. The default is 9001. | | -i *\* | An optional directory containing additional library JAR files, such as plugins and Java Database Connectivity (JDBC) drivers, to be copied into the target installation.Beginning in version 6.0, JAR files are stored in the `/deploy` folder.During an upgrade from versions earlier than 6.0, third-party JAR files are migrated from the `lib` folder to the `deploy` folder if no directory is specified.During an upgrade from version 6.0 or later, the contents of the `deploy` folder are migrated to the new `/deploy` folder if no directory is specified. | | *\* | The `PA_HOME` for the source PingAccess version. | | -l *\* | An optional path to the PingAccess license file to use for the target version. If not specified, the existing license is reused. | | -j *\* | An optional path to a file with Java Virtual Machine (JVM) *(tooltip: \
\

A virtual machine that allows a computer to run Java programs and programs that are compiled to Java bytecode.\

\
)* options to use for the new PingAccess instance during the upgrade. | | -s \| --silent | Run the upgrade with no user input required. To use this option, specify the source version's credentials using environment variables. | ### Environment variables You can specify the username and password for the source version using these environment variables: * `PA_SOURCE_API_USERNAME` – The username for the source version's Admin API. This should be set to Administrator. * `PA_SOURCE_API_PASSWORD` – The basic authorization password for the Administrator in the source version's Admin API. ### Java virtual machine (JVM) memory options You can include these options in the JVM memory options file. Memory amounts use `m` or `g` to specify the unit. * `-Xms` – Minimum heap size * `-Xmx` – Maximum heap size * `-XX:NewSize=` – Minimum size for the Young Gen space * `-XX:MaxNewSize=` – Maximum size for the Young Gen space * `-XX:+UseParallelGC` – Specifies that the parallel garbage collector should be used You can copy the existing `/conf/jvm-memory.options` file to create a JVM memory options file for the upgrade. ### Example ``` #Sample JVM Memory options file -Xms512m -Xmx1g -XX:NewSize=256m -XX:MaxNewSize=512m -XX:+UseParallelGC ```