TeamCity 2018.x Documentation

[Documentation for Previous Versions]


You are viewing the documentation of TeamCity 2018.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the [listing] to choose the documentation corresponding to your TeamCity version.


Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  1. 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)
  2. Check your license keys unless you are upgrading within bugfix releases of the same major X.X version
  3. Download the new TeamCity version (extended download options)
  4. Carefully review the Upgrade Notes
  5. Consider probing the upgrade on a test server
  6. If you have non-bundled plugins installed, check plugin pages for compatibility with the new version and upgrade/uninstall the plugins if necessary


  1. Back up the current TeamCity data
  2. Perform the upgrade steps:

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.


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 <TeamCity Data Directory>\config\ 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.


  • some customizations, e.g. installations with changed server context, are not supported by automatic update
  • only manual upgrade is possible if the server is deployed from a .war distribution, or runs under the official TeamCity Docker container, started with AWS CloudFormation template or  Azure Azure Resource Manager template.
  • the Windows uninstaller is not updated during the upgrade, so after several updates, old TeamCity version will still be noted in Windows lists. During the uninstallation, not all of the TeamCity installation files might be deleted.
  • the bundled Java is not updated
  • with several nodes installation, only the main TeamCity server can be auto-updated, the Running Builds node needs to be updated manually.


It is recommended for all users to regularly update their IDE plugins to the latest version compatible with the TeamCity server version in use. At least to the version available from the TeamCity server's Tools section on user profile.
Generally, versions of the IntelliJ IDEA TeamCity plugin, Eclipse TeamCity plugin, and Visual Studio TeamCity Addin have to be the same as the TeamCity server version. Users with non-matching plugin versions get a message on an attempt to log in to the TeamCity server with a non-matching version.
The only exception is TeamCity versions 9.0 - 9.1.x, which use a compatible protocol, and any plugin of these versions can be used with any server of these versions. Updating IDE plugins to the matching server version is still recommended.

Upgrading Build Agents



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