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. 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.
  2. Note the username used to run the TeamCity server. You will need it during the new version installation.
  3. If you have any of the Windows service settings customized, store them to repeat the customizations later.
  4. Note if you are using 64 bit Java to run the service (e.g. check for "64" in "Java VM info" on the server's Administration / | Diagnostics or in a thread dump), consider backing up <TeamCity home>\jre directory.
  5. (optional as these will not be overwritten by the upgrade) If you have any customizations of the bundled Tomcat server (like port, https protocol, etc.), JRE, etc. Backup those to repeat the customizations later.
  6. Note if you have local agent installed (though, it is not recommended to have a local agent) so that you can select the same option in the installer.
  7. Run the new installer and point it to the same place TeamCity is installed into ( the location used for installation is remembered automatically). Confirm uninstalling the previous installation. The TeamCity uninstaller ensures proper uninstallation, but you might want to make sure the TeamCity server installation directory does not contain any non-customized files after uninstallation finishes. If there are any, backup/remove them before proceeding with the installation.


    The main server configuration file <TeamCity Home Directory>/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. Other files under conf can be overwitten to their default content as well, so if you have made manual modifications in those, check them after the upgrade.

  8. If prompted, specify the <TeamCity data directory> used by the previous installation.
  9. (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 an external database).
  10. 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.
  11. If you were using 64 bit Java to run the server restore the <TeamCity home>\jre directory previously backed up or repeat the 64 bit Java installation steps.
  12. If you use a customized Log4j configuration in the conf\teamcity-server-log4j.xml file and want to preserve it (note, however, that customizing the file is actually not recommended, use logging presets instead), compare and merge conf\teamcity-server-log4j.xml.backup created by the installer from the existing copy with the default file saved with the default name. Since TeamCity 2017.1 compare the conf\teamcity-*-log4j.xml.dist file with the corresponding conf\teamcity-*-log4j.xml file and make sure that .xml file contains all the .dist file defaults. It is recommended to copy the .dist file over to the corresponding .xml file until you really need the changed logging configuration.
  13. Start up the TeamCity server (and agent, if it was installed together with the installer).
  14. Review the TeamCity Maintenance Mode page to make sure there are no problems encountered, and confirm the upgrade by clicking the corresponding button. Only after that all data will be converted to the newer format.