- Reference
- Module:
- Microsoft.PowerShell.Utility
Formats the output as a table.
Syntax
Format-Table [[-Property] <Object[]>] [-AutoSize] [-RepeatHeader] [-HideTableHeaders] [-Wrap] [-GroupBy <Object>] [-View <string>] [-ShowError] [-DisplayError] [-Force] [-Expand <string>] [-InputObject <psobject>] [<CommonParameters>]Description
The Format-Table cmdlet formats the output of a command as a table with the selected properties ofthe object in each column. The object type determines the default layout and properties that aredisplayed in each column. You can use the Property parameter to select the properties that youwant to display.
PowerShell uses default formatters to define how object types are displayed. You can use .ps1xmlfiles to create custom views that display an output table with specified properties. After a customview is created, use the View parameter to display the table with your custom view. For moreinformation about views, seeabout_Format.ps1xml.
You can use a hash table to add calculated properties to an object before displaying it and tospecify the column headings in the table. To add a calculated property, use the Property orGroupBy parameter. For more information about hash tables, seeabout_Hash_Tables.
Examples
Example 1: Format PowerShell host
This example displays information about the host program for PowerShell in a table.
Get-Host | Format-Table -AutoSizeThe Get-Host cmdlet gets System.Management.Automation.Internal.Host.InternalHost objects thatrepresent the host. The objects are sent down the pipeline to Format-Table and displayed in atable. The AutoSize parameter adjusts the column widths to minimize truncation.
Example 2: Format processes by BasePriority
In this example, processes are displayed in groups that have the same BasePriority property.
Get-Process | Sort-Object -Property BasePriority | Format-Table -GroupBy BasePriority -WrapThe Get-Process cmdlet gets objects that represent each process on the computer and sends themdown the pipeline to Sort-Object. The objects are sorted in the order of their BasePriorityproperty.
The sorted objects are sent down the pipeline to Format-Table. The GroupBy parameter arrangesthe process data into groups based on their BasePriority property's value. The Wrapparameter ensures that data isn't truncated.
Example 3: Format processes by start date
This example displays information about the processes running on the computer. The objects aresorted and Format-Table uses a view to group the objects by their start date.
Get-Process | Sort-Object StartTime | Format-Table -View StartTimeGet-Process gets the System.Diagnostics.Process objects that represent the processes runningon the computer. The objects are sent down the pipeline to Sort-Object, and are sorted based onthe StartTime property.
The sorted objects are sent down the pipeline to Format-Table. The View parameter specifiesthe StartTime view that's defined in the PowerShell DotNetTypes.format.ps1xml file forSystem.Diagnostics.Process objects. The StartTime view converts each processes start time toa short date and then groups the processes by the start date.
The DotNetTypes.format.ps1xml file contains a Priority view for processes. You can create yourown format.ps1xml files with customized views.
Example 4: Use a custom view for table output
In this example, a custom view displays a directory's contents. The custom view adds theCreationTime column to the table output for System.IO.DirectoryInfo andSystem.IO.FileInfo objects created by Get-ChildItem.
The custom view in this example was created from the view defined in PowerShell source code. Formore information about views and the code used to create this example's view, seeabout_Format.ps1xml.
Get-ChildItem -Path C:\Test | Format-Table -View mygciviewDirectory: C:\TestMode LastWriteTime CreationTime Length Name---- ------------- ------------ ------ ----d----- 11/4/2019 15:54 9/24/2019 15:54 Archivesd----- 8/27/2019 14:22 8/27/2019 14:22 Drawingsd----- 10/23/2019 09:38 2/25/2019 09:38 Files-a---- 11/7/2019 11:07 11/7/2019 11:07 11345 Alias.txt-a---- 2/27/2019 15:15 2/27/2019 15:15 258 alias_out.txt-a---- 2/27/2019 15:16 2/27/2019 15:16 258 alias_out2.txtGet-ChildItem gets the contents of the current directory, C:\Test. TheSystem.IO.DirectoryInfo and System.IO.FileInfo objects are sent down the pipeline.Format-Table uses the View parameter to specify the custom view mygciview that includesthe CreationTime column.
The default Format-Table output for Get-ChildItem doesn't include the CreationTime column.
Example 5: Use properties for table output
This example uses the Property parameter to display all the computer's services in a two-columntable that shows the properties Name and DependentServices.
Get-Service | Format-Table -Property Name, DependentServicesGet-Service gets all the services on the computer and sends theSystem.ServiceProcess.ServiceController objects down the pipeline. Format-Table uses theProperty parameter to specify that the Name and DependentServices properties aredisplayed in the table.
Name and DependentServices are two of the object type's properties. To view all theproperties: Get-Service | Get-Member -MemberType Properties.
Example 6: Format a process and calculate its running time
This example displays a table with the process name and total running time for the local computer'snotepad processes. The total running time is calculated by subtracting the start time of eachprocess from the current time.
Get-Process notepad | Format-Table ProcessName, @{Label="TotalRunningTime"; Expression={(Get-Date) - $_.StartTime}}ProcessName TotalRunningTime----------- ----------------notepad 03:20:00.2751767notepad 00:00:16.7710520Get-Process gets all the local computer's notepad processes and sends the objects down thepipeline. Format-Table displays a table with two columns: ProcessName, a Get-Processproperty, and TotalRunningTime, a calculated property.
The TotalRunningTime property is specified by a hash table with two keys, Label andExpression. The Label key specifies the property name. The Expression key specifies thecalculation. The expression gets the StartTime property of each process object and subtracts itfrom the result of a Get-Date command, which gets the current date and time.
Example 7: Format Notepad processes
This example uses Get-CimInstance to get the running time for all notepad processes on thelocal computer. You can use Get-CimInstance with the ComputerName parameter to get informationfrom remote computers.
$Processes = Get-CimInstance -Class win32_process -Filter "name='notepad.exe'"$Processes | Format-Table ProcessName, @{ Label = "Total Running Time" Expression={(Get-Date) - $_.CreationDate}}ProcessName Total Running Time----------- ------------------notepad.exe 03:39:39.6260693notepad.exe 00:19:56.1376922Get-CimInstance gets instances of the WMI Win32_Process class that describes all the localcomputer's processes named notepad.exe. The process objects are stored in the $Processesvariable.
The process objects in the $Processes variable are sent down the pipeline to Format-Table, whichdisplays the ProcessName property and a new calculated property, Total Running Time.
The command assigns the name of the new calculated property, Total Running Time, to theLabel key. The Expression key's script block calculates how long the process has beenrunning by subtracting the processes creation date from the current date. The Get-Date cmdlet getsthe current date. The creation date is subtracted from the current date. The result is the value ofTotal Running Time.
Example 8: Troubleshooting format errors
The following examples show the results of adding the DisplayError or ShowError parameterswith an expression.
Get-Date | Format-Table DayOfWeek,{ $_ / $null } -DisplayErrorDayOfWeek $_ / $null--------- ------------Wednesday #ERRGet-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowErrorDayOfWeek $_ / $null--------- ------------WednesdayInvalidArgument: Failed to evaluate expression " $_ / $null ".Parameters
-AutoSize
Indicates that the cmdlet adjusts the column size and number of columns based on the width of thedata. By default, the column size and number are determined by the view.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DisplayError
Indicates that the cmdlet displays errors on the command line. This parameter can be used as adebugging aid when you're formatting expressions in a Format-Table command and need totroubleshoot the expressions.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Expand
Specifies the format of the collection object and the objects in the collection. This parameter isdesigned to format objects that support theICollection(System.Collections) interface. The default value is EnumOnly.The acceptable values for this parameter are as follows:
- EnumOnly: Displays the properties of the objects in the collection.
- CoreOnly: Displays the properties of the collection object.
- Both: Displays the properties of the collection object and the properties of objects in thecollection.
| Type: | String |
| Accepted values: | CoreOnly, EnumOnly, Both |
| Position: | Named |
| Default value: | None |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Force
Indicates that the cmdlet directs the cmdlet to display all the error information. Use with theDisplayError or ShowError parameter. By default, when an error object is written to theerror or display streams, only some error information is displayed.
Also required when formatting certain .NET types. For more information, see the Notessection.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-GroupBy
Specifies sorted output in separate tables based on a property value. For example, you can useGroupBy to list services in separate tables based on their status.
Enter an expression or a property. The GroupBy parameter expects that the objects are sorted.Use the Sort-Object cmdlet before using Format-Table to group the objects.
The value of the GroupBy parameter can be a new calculated property. The calculated property canbe a script block or a hash table. Valid key-value pairs are:
- Name (or Label) -
<string> - Expression -
<string>or<script block> - FormatString -
<string>
For more information, seeabout_Calculated_Properties.
| Type: | Object |
| Position: | Named |
| Default value: | None |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-HideTableHeaders
Omits the column headings from the table.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-InputObject
Specifies the objects to format. Enter a variable that contains the objects, or type a command orexpression that gets the objects.
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Property
Specifies the object properties that appear in the display and the order in which they appear. Typeone or more property names, separated by commas, or use a hash table to display a calculatedproperty. Wildcards are permitted.
If you omit this parameter, the properties that appear in the display depend on the first object'sproperties. For example, if the first object has PropertyA and PropertyB but subsequentobjects have PropertyA, PropertyB, and PropertyC, then only the PropertyA andPropertyB headers are displayed.
The Property parameter is optional. You can't use the Property and View parameters inthe same command.
The value of the Property parameter can be a new calculated property. The calculated propertycan be a script block or a hash table. Valid key-value pairs are:
- Name (or Label)
<string> - Expression -
<string>or<script block> - FormatString -
<string> - Width -
<int32>- must be greater than0 - Alignment - value can be
Left,Center, orRight
For more information, seeabout_Calculated_Properties.
| Type: | Object[] |
| Position: | 0 |
| Default value: | None |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-RepeatHeader
Repeats displaying the header of a table after every screen full. The repeated header is useful whenthe output is piped to a pager such as less or more or paging with a screen reader.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ShowError
This parameter sends errors through the pipeline. This parameter can be used as a debugging aid whenyou're formatting expressions in a Format-Table command and need to troubleshoot the expressions.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-View
Beginning in PowerShell 6, the default views are defined in PowerShell C# source code. The*.format.ps1xml files from PowerShell 5.1 and earlier versions don't exist in PowerShell 6 andlater versions.
The View parameter lets you specify an alternate format or custom view for the table. You canuse the default PowerShell views or create custom views. For more information about how to create acustom view, see about_Format.ps1xml.
The alternate and custom views for the View parameter must use the table format, otherwise,Format-Table fails. If the alternate view is a list, use the Format-List cmdlet. If thealternate view isn't a list or a table, use the Format-Custom cmdlet.
You can't use the Property and View parameters in the same command.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Wrap
Displays text that exceeds the column width on the next line. By default, text that exceeds thecolumn width is truncated.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
PSObject
You can pipe any object to this cmdlet.
Outputs
Microsoft.PowerShell.Commands.Internal.Format
This cmdlet returns format objects that represent the table.
Notes
PowerShell includes the following aliases for Format-Table:
- All platforms:
ft
PowerShell 7.2 introduced new features to colorize output. The colors can be managed using the$PSStyle automatic variable. The $PSStyle.Formatting.TableHeader property defines the color usedfor the header of the table displayed by Format-Table. For more information about this setting,see about_ANSI_Terminals.
If you want to use Format-Table with the Property parameter, you need to include the Forceparameter under any of the following conditions:
The input objects are normally formatted out-of-band using the
ToString()method. This appliesto[string]and .NET primitive types, which are a superset of the built-in numeric types such as[int],[long], and others.The input objects have no public properties.
The input objects are instances of the wrapper types PowerShell uses for output streams otherthan the Success output stream. This applies only when these wrapper types are sent to the Successoutput stream that requires either having captured them via common parameters such asErrorVariable first or using a redirection such as
*>&1.The wrapper types include:
- System.Management.Automation.ErrorRecord
- System.Management.Automation.WarningRecord
- System.Management.Automation.VerboseRecord
- System.Management.Automation.DebugRecord
- System.Management.Automation.InformationRecord
- about_Calculated_Properties
- about_Format.ps1xml
- about_Hash_Tables
- Export-FormatData
- Format-Custom
- Format-Hex
- Format-List
- Format-Wide
- Get-FormatData
- Get-Member
- Get-CimInstance
- Update-FormatData