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

Skip to end of metadata
Go to start of metadata

The PowerShell build runner is specifically designed to run PowerShell scripts. 

The plugin responsible for PowerShell integration has been opensourced on GitHub: https://github.com/JetBrains/teamcity-powershell



If you need to run a PowerShell script with elevated permissions, consider using the TeamCity RunAs plugin.

On this page:

Cross-Platform PowerShell

Since TeamCity 2017.1, TeamCity provides support for PowerShell on Linux and Mac OS: download a PowerShell package for your platform and install it on the TeamCity agent.

PowerShell Settings






List of PowerShell versions supported by TeamCity. It is passed to powershell.exe as the -Version command line argument.

PowerShell run mode


Select the desired execution mode on a x64 machine:


Specify a version (e.g. 1.0, 2.0, etc.). It will be compared to the version installed on the agent, and an appropriate requirement will be added.
For Core editions, it will be used as the lower bound.
On Desktop editions, the exact version will be used (-Version command line argument will be added).

If the version field is left blank, no lower bound on the version requirement will be added, no -Version argument will be used on Desktop editions of PowerShell.


Select platform bitness:

  • x64 - 64-bit, default, the corresponding requirement will be added
  • x86 - 32-bit, the corresponding requirement will be added
  • Auto - when it is selected, no platform requirement will be added to the build configuration, and if both 32-bit and 64-bit PowerShells are installed, 64-bit will be preferred.



Select a PowerShell edition to be used: (since TeamCity 2017.1)

  • Desktop - closed-source edition bundled with Windows, available only on Windows platforms.
  • Core - open-source edition based on .Net Core, cross-platform, 64-bit only

Format stderr output as:


Specify how the error output is handled by the runner:

  • error: any output to stderr is handled as an error
  • warning: default; any output to stderr is handled as a warning


    To fail a build if "an error message is logged by build runner" (see Build Failure Conditions), change the default setting of the Error Output selector from warning to error.

Working directory


Specify the path to the build working directory.



Select whether you want to enter the script right in TeamCity, or specify a path to the script:

  • File: Enter the path to a PowerShell file. The path has to be relative to the checkout directory.
  • Source: Enter the PowerShell script source. Note that TeamCity parameter references will be replaced in the code.


    There is an issue with PowerShell 2.0 not returning the correct exit code when the script contains explicitly defined parameters. As a workaround, either upgrade your PowerShell or to use [Environment]::Exit(code).

Script execution mode


Specify the PowerShell script execution mode. By default, PowerShell may not allow execution of arbitrary .ps1 files. TeamCity will try to supply the -ExecutionPolicy ByPass argument.
If you've selected Execute .ps1 script from external file, your script should be signed or you should make PowerShell allow execution of arbitrary .ps1 files.
If the execution policy doesn't allow running your scripts, select Put script into PowerShell stdin mode to avoid this issue.

The -Command mode is deprecated and is not recommended for use with PowerShell of version greater than 1.0

Script arguments


Available if "Script execution mode" option is set to "Execute .ps1 script from external file". Specify here arguments to be passed into PowerShell script.

Escaping special symbols


TeamCity calls powershell.exe from the console of your operating system (command prompt on Windows, bash or other on Linux).

If parameters containing special symbols are passed to your PowerShell script in double quotes, make sure these characters are properly escaped: use the escape rules depending on your interpreter, e.g. on Windows, if a PowerShell script argument ends with a backslash, use the backslash as the escape symbol for TeamCity to correctly interpret it: "foo\\"

Additional command line parameters


Specify parameters to be passed to powershell.exe.

Interaction with TeamCity

Attention must be paid when using PowerShell to interact with TeamCity through service messages.
PowerShell tends to wrap strings written to the console with commands like Write-Output, Write-Error and similar (see TW-15080). To avoid this behavior, either use the Write-Host command, or adjust the buffer length manually:

Error Handling

Due to this issue in PowerShell itself that causes zero exit code to be always returned to a caller, TeamCity cannot always detect whether the script has executed correctly or not. We recommend several approaches that can help in detecting script execution failures:

  • Manually catching exceptions and explicitly returning exit code
    The PowerShell plugin does not use the cmd wrapper around powershell.exe. It makes returning the explicit exit code possible.

  • Setting Error Output to Error and adding a build failure condition
    In case syntax errors and exceptions are present, PowerShell writes them to stderr. To make TeamCity fail the build, set Error Output option to Error and add a build failure condition that will fail the build on any error output.
  • Failing build on certain message in build log
    Add a build failure condition that will fail the build on a certain message (say "POWERSHELL ERROR") in the build log.

Handling Output

To properly handle non-ASCII output from PowerShell, the correct encoding must be set both on the PowerShell side and on the TeamCity side.

  • To set the output encoding for PowerShell to UTF-8, add the following line to the beginning of your PowerShell script:

  • To set the encoding on the TeamCity agent side, either set the java launch option -Dfile.encoding=UTF-8, or set the build configuration parameter teamcity.runner.commandline.stdstreams.encoding value to UTF-8

Temporary Files

The TeamCity PowerShell plugin uses temporary files as an entry point; these files are created in the build temporary folder and removed after the PowerShell build step is finished. To keep the files, set  the powershell.keep.generated or teamcity.dont.delete.temp.files configuration parameter to true.

The PowerShell support is implemented as an open-source plugin. For development links refer to the plugin's page.

  • No labels


  1. When I use Powershell runner, I see the script options of FIle and Source Code.

    Then there is the script execution mode of Execute ps1 from external file and Put script into PowerShell stdin with "-Command -" argument. 

    If I select Source Code as Script, I get Script Source.

    So my question is it acceptable to use Source Code and Execute ps1 from external file or is it supposed to select the appropriate script execution mode based on the selected script option?

    1. Yes, it is acceptable. The first option describes where to get the script, the second - how to execute it

  2. I have followed all the instructions for installing powershell on a mac agent, but I still cannot get the powershell_64 requirement to be met. It is not listed in the Agent Parameters > Configuration Parameters page for my agent.


    I have tried upgrading my server to the latest version, upgrading and reinstalling and restarting my agent, but nothing works, please help.

    1. What TeamCity version are you using? Cross-platform PowerShell is only enabled by default since RC build 46446 (See release notes)


      1. Thanks. I am using 10.0.5 (42677), which I thought was the latest. Where do I find that release candidate? This page says this works since TeamCity 2017.1,

        1. Here is the page that contains tha latest public build: Download Latest

  3. in Powershell step, I use this code to replace "\" with "_" but it doesn't work and keep the variable as it is 

    $str = 'start\end\egypt'
    $str = $str -replace '\\' , '_'
    echo $str


    still return "start\end\egypt" not "start_end_egypt"

    in Powershell IDE it's working fine but in TeamCity powershell it doesn't give me the same results 


  4. Using the PowerShell, I wonder, how I can provide values to use within following build steps.

    In my case i want to use a Product-Version of a externally provided package - ideally overriding a value of a build configuration parameter:

    %env.newVersion% = (get-item "<ressource-path>").VersionInfo.ProductVersion;

    (pseudo-code, I know, it will not work like this)

    1. I understand, this should work, but sadly doesn't:


      $newExternalVersion = (get-item "%env.ExternalTrunkLatestBuildVersionPath%").VersionInfo.ProductVersion;
      Write-Host "##teamcity[setParameter name='env.NewExternalTrunkProductVersion' value='$newExternalVersion-%build.counter%']";
      Write-Host "##teamcity[buildNumber '%env.NewExternalTrunkProductVersion%']";


      Any help would be appreciated!

      1. Got it:

        $newExternalVersion = (get-item "%env.ExternalTrunkLatestBuildVersionPath%").VersionInfo.ProductVersion;
        Write-Output "##teamcity[buildNumber '$newExternalVersion-%build.counter%']";