Out-File
Sends output to a file.
Syntax
Out-File
[-FilePath] <string>
[[-Encoding] <Encoding>]
[-Append]
[-Force]
[-NoClobber]
[-Width <int>]
[-NoNewline]
[-InputObject <psobject>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Out-File
[[-Encoding] <Encoding>]
-LiteralPath <string>
[-Append]
[-Force]
[-NoClobber]
[-Width <int>]
[-NoNewline]
[-InputObject <psobject>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
The Out-File
cmdlet sends output to a file. It implicitly uses PowerShell's formatting system to
write to the file. The file receives the same display representation as the terminal. This means
that the output may not be ideal for programmatic processing unless all input objects are strings.
Redirecting the output of a PowerShell command (cmdlet, function, script) using the redirection
operator (>
) is functionally equivalent to piping to Out-File
with no extra parameters.
PowerShell 7.4 changed the behavior of the redirection operator when used to redirect the stdout
stream of a native command. For more information about redirection, see
about_Redirection.
Examples
Example 1: Send output and create a file
This example shows how to send a list of the local computer's processes to a file. If the file does
not exist, Out-File
creates the file in the specified path.
Get-Process | Out-File -FilePath .\Process.txt
Get-Content -Path .\Process.txt
NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName
------ ----- ----- ------ -- -- -----------
29 22.39 35.40 10.98 42764 9 Application
53 99.04 113.96 0.00 32664 0 CcmExec
27 96.62 112.43 113.00 17720 9 Code
The Get-Process
cmdlet gets the list of processes running on the local computer. The Process
objects are sent down the pipeline to the Out-File
cmdlet. Out-File
uses the FilePath
parameter and creates a file in the current directory named Process.txt. The Get-Content
command gets content from the file and displays it in the PowerShell console.
Example 2: Prevent an existing file from being overwritten
This example prevents an existing file from being overwritten. By default, Out-File
overwrites
existing files.
Get-Process | Out-File -FilePath .\Process.txt -NoClobber
Out-File : The file 'C:\Test\Process.txt' already exists.
At line:1 char:15
+ Get-Process | Out-File -FilePath .\Process.txt -NoClobber
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Get-Process
cmdlet gets the list of processes running on the local computer. The Process
objects are sent down the pipeline to the Out-File
cmdlet. Out-File
uses the FilePath
parameter and attempts to write to a file in the current directory named Process.txt. The
NoClobber parameter prevents the file from being overwritten and displays a message that the
file already exists.
Example 3: Send output to a file in ASCII format
This example shows how to encode output with a specific encoding type.
$Procs = Get-Process
Out-File -FilePath .\Process.txt -InputObject $Procs -Encoding ASCII -Width 50
The Get-Process
cmdlet gets the list of processes running on the local computer. The Process
objects are stored in the variable, $Procs
. Out-File
uses the FilePath parameter and
creates a file in the current directory named Process.txt. The InputObject parameter passes
the process objects in $Procs
to the file Process.txt. The Encoding parameter converts
the output to ASCII format. The Width parameter limits each line in the file to 50
characters so some data might be truncated.
Example 4: Use a provider and send output to a file
This example shows how to use the Out-File
cmdlet when you aren't in a FileSystem provider
drive. Use the Get-PSProvider
cmdlet to view the providers on your local computer. For more
information, see about_Providers.
PS> Set-Location -Path Alias:
PS> Get-Location
Path
----
Alias:\
PS> Get-ChildItem | Out-File -FilePath C:\TestDir\AliasNames.txt
PS> Get-Content -Path C:\TestDir\AliasNames.txt
CommandType Name
----------- ----
Alias % -> ForEach-Object
Alias ? -> Where-Object
Alias ac -> Add-Content
Alias cat -> Get-Content
The Set-Location
command uses the Path parameter to set the current location to the registry
provider Alias:
. The Get-Location
cmdlet displays the complete path for Alias:
.
Get-ChildItem
sends objects down the pipeline to the Out-File
cmdlet. Out-File
uses the
FilePath parameter to specify the complete path and filename for the output,
C:\TestDir\AliasNames.txt. The Get-Content
cmdlet uses the Path parameter and displays
the file's content in the PowerShell console.
Example 5: Set file output width for entire scope
This example uses $PSDefaultParameterValues
to set the Width
parameter for all invocations of
Out-File
and the redirection operartors (>
and >>
) to 2000. This ensures that everywhere
within the current scope that you output table formatted data to file, PowerShell uses a line width
of 2000 instead of a line width determined by the PowerShell host's console width.
function DemoDefaultOutFileWidth() {
try {
$PSDefaultParameterValues['out-file:width'] = 2000
$logFile = "$pwd\logfile.txt"
Get-ChildItem Env:\ > $logFile
Get-Service -ErrorAction Ignore |
Format-Table -AutoSize |
Out-File $logFile -Append
Get-Process | Format-Table Id,SI,Name,Path,MainWindowTitle >> $logFile
}
finally {
$PSDefaultParameterValues.Remove('out-file:width')
}
}
DemoDefaultOutFileWidth
For more information about $PSDefaultParameterValues
, see
about_Preference_Variables.
Parameters
-Append
Adds the output to the end of an existing file.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
Type: | SwitchParameter |
Aliases: | cf |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Encoding
Specifies the type of encoding for the target file. The default value is utf8NoBOM
.
The acceptable values for this parameter are as follows:
ascii
: Uses the encoding for the ASCII (7-bit) character set.ansi
: Uses the encoding for the for the current culture's ANSI code page. This option was added in PowerShell 7.4.bigendianunicode
: Encodes in UTF-16 format using the big-endian byte order.bigendianutf32
: Encodes in UTF-32 format using the big-endian byte order.oem
: Uses the default encoding for MS-DOS and console programs.unicode
: Encodes in UTF-16 format using the little-endian byte order.utf7
: Encodes in UTF-7 format.utf8
: Encodes in UTF-8 format.utf8BOM
: Encodes in UTF-8 format with Byte Order Mark (BOM)utf8NoBOM
: Encodes in UTF-8 format without Byte Order Mark (BOM)utf32
: Encodes in UTF-32 format.
Beginning with PowerShell 6.2, the Encoding parameter also allows numeric IDs of registered
code pages (like -Encoding 1251
) or string names of registered code pages (like
-Encoding "windows-1251"
). For more information, see the .NET documentation for
Encoding.CodePage.
Starting with PowerShell 7.4, you can use the Ansi
value for the Encoding parameter to pass
the numeric ID for the current culture's ANSI code page without having to specify it manually.
Note
UTF-7* is no longer recommended to use. As of PowerShell 7.1, a warning is written if you
specify utf7
for the Encoding parameter.
Type: | Encoding |
Accepted values: | ASCII, BigEndianUnicode, BigEndianUTF32, OEM, Unicode, UTF7, UTF8, UTF8BOM, UTF8NoBOM, UTF32 |
Position: | 1 |
Default value: | UTF8NoBOM |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-FilePath
Specifies the path to the output file.
Type: | String |
Aliases: | Path |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Force
Overrides the read-only attribute and overwrites an existing read-only file. The Force parameter doesn't override security restrictions.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-InputObject
Specifies the objects to be written to the file. Enter a variable that contains the objects or type a command or expression that gets the objects.
Type: | PSObject |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-LiteralPath
Specifies the path to the output file. The LiteralPath parameter is used exactly as it's typed. Wildcard characters aren't accepted. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. For more information, see about_Quoting_Rules.
Type: | String |
Aliases: | PSPath, LP |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-NoClobber
NoClobber prevents an existing file from being overwritten and displays a message that the file
already exists. By default, if a file exists in the specified path, Out-File
overwrites the file
without warning.
Type: | SwitchParameter |
Aliases: | NoOverwrite |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NoNewline
Specifies that the content written to the file doesn't end with a newline character. 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: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet isn't run.
Type: | SwitchParameter |
Aliases: | wi |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Width
Specifies the maximum number of characters in each line of output. Any additional characters are
truncated, not wrapped. If this parameter isn't used, the width is determined by the
characteristics of the host. The default for the PowerShell console is 80 characters. If you want
to control the width for all invocations of Out-File
as well as the redirection operators (>
and >>
), set $PSDefaultParameterValues['out-file:width'] = 2000
before using Out-File
.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
You can pipe any object to this cmdlet.
Outputs
None
This cmdlet returns no output.
Notes
Input objects are automatically formatted as they would be in the terminal, but you can use a
Format-*
cmdlet to explicitly control the formatting of the output to the file. For example,
Get-Date | Format-List | Out-File out.txt
To send a PowerShell command's output to the Out-File
cmdlet, use the pipeline. Alternatively, you
can store data in a variable and use the InputObject parameter to pass data to the Out-File
cmdlet.
Out-File
saves data to a file but it doesn't produce any output objects to the pipeline.
PowerShell 7.2 added the ability to control how ANSI escape sequences are rendered. ANSI-decorated
output that's passed to Out-File
can be changed based on the setting of the
$PSStyle.OutputRendering
property. For more information, see
about_ANSI_Terminals.