Upgrade

TeamCity supports upgrades from any of the previous versions to the later ones. All the settings and data are preserved unless noted in the Upgrade Notes.

Before Upgrade

Before upgrading TeamCity:

For a major upgrade, review what you will be getting in What's New (follow the links at the bottom of What's New if you are upgrading not from the previous major release)
Check your license keys unless you are upgrading within bugfix releases of the same major X.X version
Download the new TeamCity version (extended download options)
Carefully review the Upgrade Notes
Consider probing the upgrade on a test server
If you have non-bundled plugins installed, check plugin pages for compatibility with the new version and upgrade/uninstall the plugins if necessary

To upgrade the server:

Back up the current TeamCity data
Perform the upgrade steps:
- Upgrading Using Windows Installer
- Manual Upgrading on Linux and for WAR Distributions

If you plan to upgrade a production TeamCity installation, it is recommended to install a test server and check its functioning in your environment before upgrading the main one.

Licensing

Before upgrade, please make sure the maintenance period of your licenses is not yet elapsed (use Administration | Licenses TeamCity server web UI page to list your license keys). The licenses are valid only for the versions of TeamCity with the effective release date within the maintenance period. See the effective release date at the page.

Typically all the bugfix updates (releases with changes in the third release number) use the same effective release date (that of the major/minor release).

Please note that the licensing policy in TeamCity versions 5.0 and above are different from that of the previous TeamCity versions. Review the Licensing Policy page and the Licensing and Upgrade section on the official site. If you are evaluating a newer version, you can get an evaluation license on the download page. Please note that each TeamCity version can be evaluated only once. To extend the evaluation period, contact JetBrains sales department.

Upgrading TeamCity Server

TeamCity supports upgrades from any of the previous versions to the current one. Unless specifically noted, downgrades with preserving the data are not possible with changing major.minor version and are possible within bugfix releases (without changing major.minor version).

The general policy is that bugfix updates (changes in the Z part of X.Y.Z TeamCity version) do not change data format, so you can freely upgrade/downgrade within the bugfix versions. However, when upgrading to the next major or minor version (changed X or Y in X.Y.Z TeamCity version), you will not be able to downgrade with the data preservation: you will need to restore a backup of the appropriate version.

On upgrade, all the TeamCity configuration settings and other data are preserved unless noted in Upgrade Notes. If you have customized TeamCity installation (like Tomcat server settings change), you will need to repeat the customization after the upgrade.

Agents connected to the server are upgraded automatically.

Important note on TeamCity data structure upgrade TeamCity server stores its data in the database and in TeamCity Data Directory on the file system. Different TeamCity versions use different data structure of the database and data directory. Upon starting newer version of TeamCity, the data is kept in the old format until you confirm the upgrade and data conversion on the Maintenance page in the web UI. Until you do so, you can back up the old data; however, once the upgrade is complete, the data is updated to a newer format. Once the data is converted, downgrade to the previous TeamCity versions which uses different data format is not possible! There are several important issues with data format upgrade:

Data structure downgrade is not possible. Once newer TeamCity version changes the data format of database and data directory, you cannot use this data to run an older TeamCity version. Please ensure you backup the data before upgrading TeamCity.
Both the database and the data directory should be upgraded simultaneously. Ensure that during the first start of the newer server it uses the correct TeamCity Data Directory that in its turn has the correct database configured in the < >\config\database.properties file. Also make sure the data directory is complete (e.g. all the build logs, artifacts, etc. are in place), no data directory content supports copying from the data directory of the older server versions.

If you did performed inconsistent upgrade accidentally, check the recovery instructions.

Upgrading Using Windows Installer

Create a backup. When upgrading from TeamCity 6.0+ you will also have a chance to create a backup with the "basic" profile on the TeamCity Maintenance Mode page on the updated TeamCity start.
Note the username used to run the TeamCity server. You will need it during the new version installation.
(optional as these will not be overwritten by the upgrade) If you have any of the Windows service settings customized, store them to repeat the customizations later. The same applies to customizations of the bundled Tomcat server (like port, https protocol, etc.) and JRE, if any.
Run the new installer. Confirm uninstalling the previous installation. After uninstallation finishes, make sure the TeamCity server installation directory does not contain any non-customized files. If there are any, backup/remove them before proceeding with installation. Since TeamCity 9.1, the TeamCity uninstaller ensures proper uninstallation (see a related issue TW-39884).
Since TeamCity 9.1, the main server configuration file < >/conf/server.xml is updated automatically when there were no changes to it since the last installation. If modification were made, the installer will detect them and backup the old server.xml file displaying a warning about the overwrite and the backup file location.
When prompted, specify the <TeamCity data directory> used by the previous installation.
(optional as these will not be overwritten by the upgrade) Make sure you have the external database driver installed (this applies only if you use external database).
Check and restore any customizations of Windows services and Tomcat configuration that you need. When upgrading from versions 7.1 and earlier, make sure to transfer the server memory setting to the environment variables.
If you use customized Log4J configuration in conf\teamcity-server-log4j.xml file and want to preserve those, compare and merge conf\teamcity-server-log4j.xml.backup created by installer from existing copy with the default file saved with default name.
Start up the TeamCity server (and agent, if it was installed together with the installer).
Review the TeamCity Maintenance Mode page to make sure there are no problems encountered, and confirm the upgrade by clicking corresponding button. Only after that all data will be converted to the newer format.

If you encounter errors which cannot be resolved, make sure old TeamCity is not running/does not start on boot, restart the machine and repeat the installation procedure.

Manual Upgrading using .tar.gz or .war Distributions

Please note that it is recommended to use .tar.gz or .exe TeamCity distribution. Using .war is not a recommended way to install TeamCity.

Create a backup.
Backup files customized since previous installation (most probbaly [TOMCAT_HOME]/conf/server.xml)
Remove old installation files (the entire TeamCity home directory or [TOMCAT_HOME]/webapps/TeamCity/* if you are installing from a war file). It's advised to backup the directory beforehand.
Unpack the new archive to the location where TeamCity was previously installed.
If you use Tomcat server (your own or bundled in .tar.gz TeamCity distribution), it is recommended to delete content of the work directory. Please note that this may affect other web applications deployed into the same web server.
Restore customized settings backed up in step 2 above. If you have customized [TOMCAT_HOME]/conf/server.xml file, apply your changes into the appropriate sections of the default file.
Make sure previously configured TeamCity server startup properties (if any) are still actual.
Start up the TeamCity server.
Review the TeamCity Maintenance Mode page to make sure there are no problems encountered, and confirm the upgrade by clicking corresponding button. Only after that all the configuration data and database scheme are updated by TeamCity converters.

IDE Plugins

Generally, versions of IntelliJ IDEA TeamCity plugin, Eclipse TeamCity plugin and Visual Studio TeamCity Addin should be the same as the TeamCity server version. Users with not matching plugin versions get a message on attempt to login to TeamCity server with not matching version. The only exception is that TeamCity versions 9.0 - 9.1.x use compatible protocol and any plugin of these versions can be used with any server of these verions. Updating IDE plugin to the matching server version is still recommended.

Upgrading Build Agents

#Automatic Build Agent Upgrading
Upgrading Build Agents Manually
- #Upgrading the Build Agent Windows Service Wrapper

Automatic Build Agent Upgrading

On starting TeamCity server (and updating agent distribution or plugins on the server), TeamCity agents connected to the server and correctly installed are automatically updated to the version corresponding to the server. This occurs for both server upgrades and downgrades. If there is a running build on the agent, the build finishes. No new builds are started on the agent unless agent is up to date with the server.

The agent update procedure is as follows: The agent (agent.bat, agent.sh, or agent service) will download the current agent package from the TeamCity server. When the download is complete and the agent is idle, it will start the upgrade process (the agent is stopped, the agent files are updated, and agent is restarted). This process may take several minutes depending on the agent hardware and network bandwidth. Do not interrupt the upgrade process, as doing so may cause the upgrade to fail and you will need to manually reinstall the agent.

If you see that an agent is identified as "Agent disconnected (Will upgrade)" in the TeamCity web UI, do not close the agent console or restart the agent process, but wait for several minutes.

Various console windows can open and close during the agent upgrade. Please be patient and do not interrupt the process until the agent upgrade is finished.

Upgrading Build Agents Manually

All connected agents upgrade automatically, provided they are correctly installed, so manual upgrade is not necessary.

If you need to upgrade agent manually, you can follow the steps below:

As TeamCity agent does not hold any unique information, the easiest way to upgrade an agent if to

back up <Agent Home>/conf/buildAgent.properties file.
uninstall/delete existing agent.
install the new agent version.
restore previously saved buildAgent.properties file to the same location.
start the agent.

If you need to preserve all the agent data (e.g. to eliminate clean checkouts after the upgrade), you can:

stop the agent.
delete all the directories in the agent installation present in the agent .zip distribution except conf.
unpack the .zip distribution to the agent installation directory, skipping the "conf" directory.
start the agent.

In the latter case if you run agent under Windows using service, you can also need to upgrade Windows service as described below.

Upgrading the Build Agent Windows Service Wrapper

Upgrading from TeamCity version 1.x

Version 2.0 of TeamCity migrated to new way of managing Windows service (service wrapper) for the build agent: Java Service Wrapper library.

One of advantages of using new service wrapper is ability to change any JVM parameters of the build agent process.

1.x versions installed Windows service under name agentd, while 2.x versions use TeamCity Build Agent Service <build number> name.

The service wrapper will not be migrated to new version automatically. You do not need to use the new service wrapper, unless you need its functionality (like changing agent JVM parameters).

To use new service wrapper you should uninstall old version of the agent (with Control Panel | Add/Remove Programs) and then install a new one.

If you customized the user under which the service is started, do not forget to customize it in the newly installed service.

Upgrading from TeamCity version 2.x

If the service wrapper needs an update, the new version is downloaded into the <agent>/launcher.latest folder, however the changes are not applied automatically.

To upgrade the service wrapper manually, do the following:

Ensure the <agent>/launcher.latest folder exists.
Stop the service using <agent>\bin\service.stop.bat.
Uninstall the service using service.uninstall.bat.
Backup <agent>/launcher/conf/wrapper.conf file.
Delete <agent>/launcher.
Rename <agent>/launcher.latest to <agent>/launcher.
Edit <agent>/launcher/conf/wrapper.conf file. Check that the 'wrapper.java.command' property points to the java.exe file. Leave it blank to use registry to lookup for java. Leave 'java.exe' to lookup java.exe in PATH. For a standalone agent the service value should be ../jre/bin/java, for and agent installation on the server the value should be ../../jre/bin/java. The backup version of wrapper.conf file may be used.
Install the service using <agent>\bin\service.install.bat.
Make sure the service is running under the proper user account. Please note that using SYSTEM can result in failing builds which use MSBuild/Sln2005 configurations.
Start the service using <agent>\bin\service.start.bat.
This procedure is applicable ONLY for an agent running with new service wrapper. Make sure you are not running the agentd service.

Last modified: 20 April 2023