Skip to content

Write-Host.md

Latest commit

 

History

History
303 lines (227 loc) · 8.47 KB

Write-Host.md

File metadata and controls

303 lines (227 loc) · 8.47 KB
external help file Microsoft.PowerShell.Commands.Utility.dll-Help.xml
Locale en-US
Module Name Microsoft.PowerShell.Utility
ms.date 04/01/2026
online version https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/write-host?view=powershell-7.6&WT.mc_id=ps-gethelp
schema 2.0.0
title Write-Host

Write-Host

SYNOPSIS

Writes customized output to a host.

SYNTAX

Write-Host [[-Object] <Object>] [-NoNewline] [-Separator <Object>] [-ForegroundColor <ConsoleColor>]
 [-BackgroundColor <ConsoleColor>] [<CommonParameters>]

DESCRIPTION

The Write-Host cmdlet's primary purpose is to produce for-(host)-display-only output, such as printing colored text like when prompting the user for input in conjunction with Read-Host. Write-Host uses the ToString() method to write the output. By contrast, to output data to the pipeline, use Write-Output or implicit output.

You can specify the color of text by using the ForegroundColor parameter, and you can specify the background color by using the BackgroundColor parameter. The Separator parameter lets you specify a string to use to separate displayed objects. The particular result depends on the program that is hosting PowerShell.

Note

Starting in Windows PowerShell 5.0, Write-Host is a wrapper for Write-Information. This allows you to use Write-Host to emit output to the information stream. This enables the capture or suppression of data written using Write-Host while preserving backwards compatibility.

The $InformationPreference preference variable and InformationAction common parameter do not affect Write-Host messages. The exception to this rule is -InformationAction Ignore, which effectively suppresses Write-Host output. (see "Example 5")

EXAMPLES

Example 1: Write to the console without adding a new line

Write-Host "no newline test " -NoNewline
Write-Host "second string"
no newline test second string

This command displays the string 'no newline test' with the NoNewline parameter.

A second string is written, but it ends up on the same line as the first due to the absence of a newline separating the strings.

Example 2: Write to the console and include a separator

Write-Host (2,4,6,8,10,12) -Separator ", +2= "
2, +2= 4, +2= 6, +2= 8, +2= 10, +2= 12

This command displays the even numbers from two through twelve. The Separator parameter is used to add the string , +2= (comma, space, +, 2, =, space).

Example 3: Write with different text and background colors

Write-Host (2,4,6,8,10,12) -Separator ", -> " -ForegroundColor DarkGreen -BackgroundColor White
2, -> 4, -> 6, -> 8, -> 10, -> 12

This command displays the even numbers from two through twelve. It uses the ForegroundColor parameter to output dark green text and the BackgroundColor parameter to display a white background.

Example 4: Write with different text and background colors

Write-Host "Red on white text." -ForegroundColor red -BackgroundColor white
Red on white text.

This command displays the string "Red on white text." The text is red, as defined by the ForegroundColor parameter. The background is white, as defined by the BackgroundColor parameter.

Example 5: Suppress output from Write-Host

# The following two statements can be used to effectively suppress output from Write-Host
Write-Host "I won't print" -InformationAction Ignore
Write-Host "I won't print" 6> $null

These commands effectively suppress output of the Write-Host cmdlet. The first one uses the InformationAction parameter with the Ignore Value to suppress output to the information stream. The second example redirects the information stream of the command to the $null variable and thereby suppresses it. For more information, see about_Output_Streams.

PARAMETERS

-BackgroundColor

Specifies the background color. There is no default. The acceptable values for this parameter are:

  • Black
  • DarkBlue
  • DarkGreen
  • DarkCyan
  • DarkRed
  • DarkMagenta
  • DarkYellow
  • Gray
  • DarkGray
  • Blue
  • Green
  • Cyan
  • Red
  • Magenta
  • Yellow
  • White
Type: System.ConsoleColor
Parameter Sets: (All)
Aliases:
Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ForegroundColor

Specifies the text color. There is no default. The acceptable values for this parameter are:

  • Black
  • DarkBlue
  • DarkGreen
  • DarkCyan
  • DarkRed
  • DarkMagenta
  • DarkYellow
  • Gray
  • DarkGray
  • Blue
  • Green
  • Cyan
  • Red
  • Magenta
  • Yellow
  • White
Type: System.ConsoleColor
Parameter Sets: (All)
Aliases:
Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-NoNewline

The string representations of the input objects are concatenated to form the output. No spaces or newlines are inserted between the output strings. No newline is added after the last output string.

Type: System.Management.Automation.SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Object

Objects to display in the host.

Type: System.Object
Parameter Sets: (All)
Aliases: Msg, Message

Required: False
Position: 0
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-Separator

Specifies a separator string to insert between objects displayed by the host.

Type: System.Object
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.Object

You can pipe objects to be written to the host to this cmdlet.

OUTPUTS

None

This cmdlet returns no output. It sends the objects to the host. The host displays the objects this cmdlet sends to it.

NOTES

  • When writing a collection to the host, elements of the collection are printed on the same line separated by a single space. This can be overridden with the Separator parameter.

  • Non-primitive data types such as objects with properties can cause unexpected results and not provide meaningful output. For example, @{a = 1; b = 2} | Write-Host will print System.Collections.Hashtable to the host.

    To work around this issue, you can manually create the string format you need with either string interpolation or the format operator (-f). You can also pass the object to the Out-String command before passing it to Write-Host. The following snippet shows examples of each approach:

    $ht = @{a = 1; b = 2}
# String interpolation
$ht.Keys.ForEach({ "[$_, $($ht[$_])]" }) -join ' ' | Write-Host
# Format operator
"[{0}, {1}] [{2}, {3}]" -f @('a', $ht.a, 'b', $ht.b) | Write-Host
# Out-String
$ht | Out-String | Write-Host -NoNewline

    For more information about string interpolation, see the article Everything you wanted to know about variable substitution in strings. For more information about the format operator, see about_Operators.

RELATED LINKS

Clear-Host

Out-Host

Write-Debug

Write-Error

Write-Output

Write-Progress

Write-Verbose

Write-Warning