Free Disk Space

TeamCity needs disk space on agents for builds and allocates 3 GB for it by default.

If you need more space for your builds, use the Free disk space build feature. It allows ensuring certain free disk space on the agent before the build by cleaning up old build data, such as build's checkout directories and various caches. Specify a new value for the required disk space in the build feature settings.

Note that the Free disk space build feature keeps track of the size of artifacts and automatically calculates the disk space required for resolving artifact dependencies. You do not have to take into account the size of the artifacts downloaded during the build when specifying the required disk space.

How it Works

Before the build and before each build preparation stage (updating sources), the agent will check the currently available free disk space in three locations:

agent's system
agent's temp directory
build checkout directory

All these locations have to meet the same specified requirement. If the failure condition is specified, the build will fail if either of the locations does not meet the requirement.

If the amount of disk space is less than required, the agent will try to delete the old data of other builds before proceeding.

The data cleaned includes:

the checkout directories that were marked for deletion
contents of other build's checkout directories in the reversed most recently used order
the cache of previously downloaded artifacts (that were downloaded to the agent via TeamCity artifact dependencies)
cleaning the local Docker caches
cleaning the local NuGet packages caches

If you need to make sure a checkout directory is never deleted while freeing disk space, set the system.teamcity.build.checkoutDir.expireHours property to never.

Settings

You can use the Free disk space build feature to alter the default 3 GB of required disk space. Configure the settings below:

Setting	Description
Required free space	You can specify a custom free disk space value here (in bytes or using one of the kb, mb, gb or tb suffixes).
Fail build if sufficient disk space cannot be freed	Enable to add the corresponding build failure condition.

Alternative Methods to Set Free Disk Space Value

To ensure compatibility, the value of free disk space can be specified via the properties below. However, using the Free disk space build feature is recommended as these properties can be removed in future TeamCity versions.

The properties can be defined:

globally for a build agent (in the agent's buildAgent.properties file)
for a particular build configuration by specifying its system properties.

The required free space value is defined with the following properties:

system.teamcity.agent.ensure.free.space for the build checkout directory
system.teamcity.agent.ensure.free.temp.space for the agent's temp directory

If teamcity.agent.ensure.free.temp.space is not defined, the value of the teamcity.agent.ensure.free.space property is used.

The values of these properties specify the amount of the available free disk space to be ensured before the build starts. The value should be a number followed by kb, mb, gb, kib, mib, or gib suffix. Use no suffix for bytes.
Example: system.teamcity.agent.ensure.free.space = 5gb

Here is how TeamCity will choose a free disk space value:

Use system.teamcity.agent.ensure.free.space, defined on the agent or overridden on the project or build configuration level.
If (1) is not defined, use teamcity.agent.ensure.free.space, defined on the agent or overridden on the project or build configuration level.
If (1-2) are not defined, use the custom value defined in the build feature.
If no custom values are defined, use the default value of 3 GB.

Disabling Artifacts Cache

A TeamCity build agent maintains a cache of published and downloaded build artifacts to reduce network transfers to the same agent. The cache is stored in the <Build Agent Home>\system\.artifacts_cache directory and is deleted automatically provided the Free disk space build feature is configured correctly. While downloading artifact dependencies, TeamCity automatically disables caching if there is insufficient space to store the cache.

If caching artifacts is not required, it can be turned off by adding the teamcity.agent.filecache.publishing.disabled=true configuration parameter to a project or one of its build configurations. It can be helpful when the artifacts are large and not used within TeamCity, or if the artifacts cache directory is located not on the same disk as the build checkout directory. However, the agent will still cache artifacts downloaded as artifact dependencies if there is enough space to store the cache.

Last modified: 18 May 2023