Skip to content

Out-File

SYNOPSIS

Sends output to a file.

SYNTAX

ByPath (Default)

Out-File [-FilePath] <String> [[-Encoding] <Encoding>] [-Append] [-Force] [-NoClobber] [-Width <Int32>]
 [-NoNewline] [-InputObject <PSObject>] [-WhatIf] [-Confirm] [<CommonParameters>]

ByLiteralPath

Out-File -LiteralPath <String> [[-Encoding] <Encoding>] [-Append] [-Force] [-NoClobber] [-Width <Int32>]
 [-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. When you need to specify parameters for the output, use `Out-File` rather than the redirection operator (`>`). For more information about redirection, see about_Redirection (../Microsoft.PowerShell.Core/About/about_Redirection.md).

EXAMPLES

Example 1: Send output and create a file

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

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

$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

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

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 (../Microsoft.Powershell.Core/About/about_preference_variables.md#psdefaultparametervalues).

PARAMETERS

-Append

Adds the output to the end of an existing file.

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

Required: False
Position: Named
Default value: 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.
  • `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 (/dotnet/api/system.text.encoding.codepage?view=netcore-2.2).

> [!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: System.Text.Encoding
Parameter Sets: (All)
Aliases:
Accepted values: ASCII, BigEndianUnicode, BigEndianUTF32, OEM, Unicode, UTF7, UTF8, UTF8BOM, UTF8NoBOM, UTF32

Required: False
Position: 1
Default value: UTF8NoBOM
Accept pipeline input: False
Accept wildcard characters: False

-FilePath

Specifies the path to the output file.

Type: System.String
Parameter Sets: ByPath
Aliases: Path

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

-Force

Overrides the read-only attribute and overwrites an existing read-only file. The Force parameter does not override security restrictions.

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

Required: False
Position: Named
Default value: 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: System.Management.Automation.PSObject
Parameter Sets: (All)
Aliases:

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

-LiteralPath

Specifies the path to the output file. The LiteralPath parameter is used exactly as it is typed. Wildcard characters are not 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 (../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).

Type: System.String
Parameter Sets: ByLiteralPath
Aliases: PSPath, LP

Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName)
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: System.Management.Automation.SwitchParameter
Parameter Sets: (All)
Aliases: NoOverwrite

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

-NoNewline

Specifies that the content written to the file does not 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: System.Management.Automation.SwitchParameter
Parameter Sets: (All)
Aliases:

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

-Width

Specifies the number of characters in each line of output. Any additional characters are truncated, not wrapped. If this parameter is not 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: System.Int32
Parameter Sets: (All)
Aliases:

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

-Confirm

Prompts you for confirmation before running the cmdlet.

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

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

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

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

Required: False
Position: Named
Default value: False
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.Management.Automation.PSObject

You can pipe any object to `Out-File`.

OUTPUTS

None

`Out-File` does not generate any 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 does not produce any output objects to the pipeline.

about_Providers

about_Quoting_Rules

Out-Default

Out-Host

Out-Null

Out-String

Tee-Object

Back to top