Skip to end of metadata
Go to start of metadata
You are viewing documentation of TeamCity 5.x, which is not the most recent released version of TeamCity. Please refer to the listing to choose another version.

Table of Contents

Please back up your data before any upgrade and review the Upgrade Notes.

In this section
Upgrading the TeamCity Server:

Upgrading Build Agents:

If you are planning your upgrade and consider test-driving the newer TeamCity version as a separate install, you may find How To...#Test-drive newer TeamCity version before upgrade section useful.

TeamCity supports upgrading from any version to any later version. Downgrades are not possible.

Licensing Issues

Before upgrading please check that maintenance period of your licenses is not yet elapsed. The licenses are valid only for the versions of TeamCity released within the maintenance period.

Please note that TeamCity versions 5.0 and above use new licensing policy comparing to that of previous TeamCity versions. Please review Licensing Policy section and the Licensing and Upgrade section on the official site.

If you are evaluating the newer version, you can get an evaluation license on the download page. Please note that TeamCity can be evaluated only one time. For an extension of the evaluation period, please contact JetBrains sales department.

Data Structure Upgrade

TeamCity 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 automatically updated to a newer format. There are several important issues with data format upgrade:

  • Data structure downgrade is not possible. Once you run newer TeamCity version with a specific database and data directory, you cannot use the data to run older TeamCity version. Thus, please ensure you have a backup of the data before upgrading TeamCity.
  • Both database and the data directory should be upgraded together. Thus, you should ensure that during the first start of the newer server it uses correct TeamCity Data Directory that in turn has correct database configured in <TeamCity Data Directory>\config\ file.

Upgrading Using a Windows Installer

  1. Create a backup. Ensure you have configuration files and database data backed up.
  2. Run the new installer. Confirm uninstalling the previous installation. When prompted, specify the <TeamCity data directory> used by the previous installation.
  3. Make sure you have the external database driver installed (this applies only if you use external database).
  4. If you use custom plugins that do not reside in <TeamCity Data Directory>, install them.
  5. Start up the TeamCity server (and agent, if it was installed together with the installer).

Manual Upgrading on Linux and for WAR Distributions

  1. Create a backup. Ensure you have configuration files and database data backed up.
  2. Remove old installation files (either the whole TeamCity directory or [TOMCAT_HOME]/webapps/TeamCity/* if you are installing from a war file). It's advised to backup the directory beforehand.
  3. Unpack the new archive where TeamCity was previously installed.
  4. If you use Tomcat server (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.
  5. Make sure you have the external database driver installed (this applies only if you use external database).
  6. If you use custom plugins that do not reside in <TeamCity Data Directory>, install them.
  7. Specify additional TeamCity Startup Properties, if required.
  8. Start up the TeamCity server.

All the configuration data and database scheme will by updated by our converters upon the first startup after the upgrade.

Automatic Build Agent Upgrading

On starting newer TeamCity server, TeamCity agents connected to the server are updated automatically. The agent (agent.bat,, or agent service) will download the latest agent upgrade 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. It is important not to interrupt the upgrade process, as doing so may cause the upgrade to fail and the agent will need to be manually reinstalled.

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 no manual upgrade is necessary.

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

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

  • backup <Agent Home>/conf/ file
  • uninstall/delete existing agent
  • install the new agent version
  • restore the previously saved 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 int he 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:

  1. Ensure the <agent>/launcher.latest folder exists.
  2. Stop the service using <agent>\bin\service.stop.bat.
  3. Uninstall the service using service.uninstall.bat.
  4. Backup <agent>/launcher/conf/wrapper.conf file.
  5. Delete <agent>/launcher.
  6. Rename <agent>/launcher.latest to <agent>/launcher.
  7. Edit <agent>/launcher/conf/wrapper.conf file. Check that the '' 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.
  8. Install the service using <agent>\bin\service.install.bat.
  9. 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.
  10. 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.

1 Comment

  1. I'm kind of a nervous guy when doing server upgrades. I spend a lot of time preparing, even though the upgrade looks easy. My experience has been that a hurried upgrade can leave you and your users very unhappy, with a possible stomach ache on the side.
    So, here's what gave me some nerves when upgrading from 5.1.2 to 5.1.4.
    The backup. We're running TC on a Windows box. I much prefer Linux or OS X, but I was given Windows so I live with it. I ran the UI based backup and that ran flawlessly, as it always does. Just to be "safe" I decided to back up the "data" directory with Windows. That was looking like a couple hours to complete, due to Windows incredibly slow file system. I had not allocated hours for this upgrade. After about 30 min, I killed that Windows backup process, and decided to depend on the TC backup. I think that was perfectly safe. BTW, the database (external) was also backed up separately.
    Then I ran the TC installer. It asked if I wanted to install where the previous version was installed (C: drive), and that was good. It also asked if I had an existing "config" directory. Well, I have an existing "data" directory on the E: drive and the instructions on this page say to be sure to point at the "<TeamCity data directory>." The installer said "config". Hmmm

    I pointed to the "data" directory and completed the install. That was the right thing to do, but the docs on this page are confusing. This is especially true for this nervous guy.