Import-Csv

Syntax

Import-Csv
      [[-Delimiter] <Char>]
      [[-Path] <String[]>]
      [-LiteralPath <String[]>]
      [-Header <String[]>]
      [-Encoding <String>]
      [<CommonParameters>]

Import-Csv
      [[-Path] <String[]>]
      [-LiteralPath <String[]>]
      [-UseCulture]
      [-Header <String[]>]
      [-Encoding <String>]
      [<CommonParameters>]

Description

The Import-Csv cmdlet creates table-like custom objects from the items in CSV files. Each column in the CSV file becomes a property of the custom object and the items in rows become the property values. Import-Csv works on any CSV file, including files that are generated by the Export-Csv cmdlet.

You can use the parameters of the Import-Csv cmdlet to specify the column header row and the item delimiter, or direct Import-Csv to use the list separator for the current culture as the item delimiter.

You can also use the ConvertTo-Csv and ConvertFrom-Csv cmdlets to convert objects to CSV strings (and back). These cmdlets are the same as the Export-CSV and Import-Csv cmdlets, except that they do not deal with files.

If a header row entry in a CSV file contains an empty or null value, PowerShell inserts a default header row name and displays a warning message.

Examples

Example 1: Import process objects

PS C:\> Get-Process | Export-Csv Processes.csv

PS C:\> $P = Import-Csv Processes.csv

PS C:\> $P | Get-Member





   TypeName: System.Management.Automation.PSCustomObject



Name                       MemberType   Definition

----                       ----------   ----------

Equals                     Method       bool Equals(System.Object obj)

GetHashCode                Method       int GetHashCode()

GetType                    Method       type GetType()

ToString                   Method       string ToString()

BasePriority               NoteProperty string BasePriority=8

Company                    NoteProperty string Company=Microsoft Corporation

...

PS C:\> $P | Format-Table

Name                   SI Handles VM            WS        PM        NPM    Path

----                   -- ------- --            --        --        ---    ----

ApplicationFrameHost   4  407     2199293489152 15884288  15151104  23792  C:\WINDOWS\system32\ApplicationFrameHost.exe

...

wininit                0  157     2199112204288 4591616   1630208   10376

winlogon               4  233     2199125549056 7659520   2826240   10992  C:\WINDOWS\System32\WinLogon.exe

WinStore.App           4  846     873435136     33652736  26607616  55432  C:\Program Files\WindowsApps\Microsoft.WindowsStore_11712.1001.13.0_x64__8weky...

WmiPrvSE               0  201     2199100219392 8830976   3297280   10632  C:\WINDOWS\system32\wbem\wmiprvse.exe

WmiPrvSE               0  407     2199157727232 18509824  12922880  16624  C:\WINDOWS\system32\wbem\wmiprvse.exe

WUDFHost               0  834     2199310204928 51945472  87441408  24984  C:\Windows\System32\WUDFHost.exe

This example shows how to export and then import a CSV file of process objects.

The first command uses the Get-Process cmdlet to get the processes on the local computer. It uses a pipeline operator (|) to send the process objects to the Export-Csv cmdlet, which exports the process objects to the Processes.csv file in the current directory.

The second command uses the Import-Csv cmdlet to import the processes in the Processes.csv file. Then it saves the resulting process objects in the $P variable.

The third command uses a pipeline operator to pipe the imported objects to the Get-Member cmdlet. The result shows that they are System.Management.Automation.PSCustomObject objects, not the System.Diagnostic.Process objects that Get-Process returns.

Also, because there is no entry type in the formatting files for the CSV version of the process objects, these objects are not formatted in the same way that standard process objects are formatted.

To display the objects, use the formatting cmdlets, such as Format-Table and Format-List, or pipe the objects to Out-GridView.

Example 2: Specify the delimiter

PS C:\> Get-Process | Export-Csv Processes.csv -Delimiter :

PS C:\> $P = Import-Csv Processes.csv -Delimiter :

This example shows how to use the Delimiter parameter of the Import-Csv cmdlet.

In this example, the processes are exported to a file that uses a colon (:) as a delimiter.

When importing, the Import-Csv file uses the Delimiter parameter to indicate the delimiter that is used in the file.

Example 3: Specify the current culture for the delimiter

PS C:\> Get-Process | Export-Csv Processes.csv -UseCulture

PS C:\> $P = Import-Csv Processes.csv -UseCulture

PS C:\> (Get-Culture).TextInfo.ListSeparator

,

This example shows how to use the UseCulture parameter of the Import-Csv cmdlet.

In this example the processes are exported to a file that uses the culture as a delimiter. The next command imports the objects in the Processes.csv file into the $P variable. It uses the UseCulture parameter to direct Import-Csv to use the list separator defined for the current culture.

The second command displays the list separator for the current culture. It uses the Get-Culture cmdlet to get the current culture. It uses the dot (.) method to get the TextInfo property of the current culture and the ListSeparator property of the object in TextInfo.

In this example, the command returns a comma.

Example 4: Change property names in an imported object

PS C:\> Start-Job -ScriptBlock { Get-Process } | Export-Csv Jobs.csv

PS C:\> $Header = "State", "MoreData", "StatusMessage", "Location", "Command", "StateInfo", "Finished", "InstanceId", "Id", "Name", "ChildJobs", "PSBeginTime", "PSEndTime", "PSJobTypeName", "Output", "Error", "Progress", "Verbose", "Debug", "Warning", "Information"



# Delete header from file



PS C:\> $A = Get-Content Jobs.csv

PS C:\> $A = $A[1..($A.Count - 1)]

PS C:\> $A > Jobs.csv

PS C:\> $J = Import-Csv Jobs.csv -Header $Header

PS C:\> $J





State         : Running

MoreData      : True

StatusMessage :

Location      : localhost

Command       :  Get-Process

StateInfo     : Running

Finished      : System.Threading.ManualResetEvent

InstanceId    : c41e709b-80e4-4f15-ad5f-75d1548c6b7c

Id            : 1

Name          : Jobs

ChildJobs     : System.Collections.Generic.List`1[System.Management.Automation.Job]

PSBeginTime   : 2018-01-27 1:03:00 PM

PSEndTime     :

PSJobTypeName : BackgroundJob

Output        : System.Management.Automation.PSDataCollection`1[System.Management.Automation.PSObject]

Error         : System.Management.Automation.PSDataCollection`1[System.Management.Automation.ErrorRecord]

Progress      : System.Management.Automation.PSDataCollection`1[System.Management.Automation.ProgressRecord]

Verbose       : System.Management.Automation.PSDataCollection`1[System.Management.Automation.VerboseRecord]

Debug         : System.Management.Automation.PSDataCollection`1[System.Management.Automation.DebugRecord]

Warning       : System.Management.Automation.PSDataCollection`1[System.Management.Automation.WarningRecord]

Information   : System.Management.Automation.PSDataCollection`1[System.Management.Automation.InformationRecord]

This example shows how to use the Header parameter of Import-Csv to change the names of properties in the resulting imported object.

The first command uses the Start-Job cmdlet to start a background job that runs a Get-Process command on the local computer. A pipeline operator (|) sends the resulting job object to the Export-Csv cmdlet, which converts the job object to CSV format.

The second command saves a header in the $Header variable. Unlike the default header, this header uses "MoreData" instead of "HasMoreData" and "StateInfo" instead of "JobStateInfo".

The next three commands delete the original header (the first line) from the Jobs.csv file.

The sixth command uses the Import-Csv cmdlet to import the Jobs.csv file and convert the CSV strings into a CSV version of the job object. The command uses the Header parameter to submit the alternate header. The results are stored in the $J variable.

The seventh command displays the object in the $J variable. The resulting object has "MoreData" and "StateInfo" properties, as shown in the command output.

Example 5: Create a custom object using a CSV file

PS C:\> Get-Content .\Links.csv

113207,about_Aliases

113208,about_Arithmetic_Operators

113209,about_Arrays

113210,about_Assignment_Operators

113212,about_Automatic_Variables

113213,about_Break

113214,about_Command_Precedence

113215,about_Command_Syntax

144309,about_Comment_Based_Help

113216,about_CommonParameters

113217,about_Comparison_Operators

113218,about_Continue

113219,about_Core_Commands

113220,about_Data_Section

PS C:\> $A = Import-Csv -Path .\Links.csv -Header LinkID, TopicTitle

PS C:\> $A | Get-Member





   TypeName: System.Management.Automation.PSCustomObject



Name        MemberType   Definition

----        ----------   ----------

Equals      Method       bool Equals(System.Object obj)

GetHashCode Method       int GetHashCode()

GetType     Method       type GetType()

ToString    Method       string ToString()

LinkID      NoteProperty string LinkID=113207

TopicTitle  NoteProperty string TopicTitle=about_Aliases

PS C:\> $A | Where-Object TopicTitle -Like "*alias*"



LinkID TopicTitle

------ ----------

113207 about_Aliases

This example shows how to create a custom object in Windows PowerShell by using a CSV file.

The first command uses the Get-Content cmdlet to get the Links.csv file.

The second command uses the Import-Csv cmdlet to import the Links.csv file. The command uses the Header parameter to specify "LinkId" and "TopicTitle" as property names for the new custom objects. The command saves the imported objects in the $A variable.

The third command uses the Get-Member cmdlet to get the type and members of the custom objects in the $A variable.

The output shows that Import-Csv returns a collection of custom objects ( PSCustomObject ). In addition to some default properties, the custom objects have "LinkId" and "TopicTitle" note properties.

This command shows that you can use the custom object like you would any object in Windows PowerShell.

The command pipes the custom objects in the $A variable to the Where-Object cmdlet, which gets only objects with a "TopicTitle" property that includes "alias".

The Where-Object command uses the new simplified command format that does not require symbols, script blocks, or curly braces.

Example 6: Import a CSV that is missing a value

PS C:\> Get-Content "\\Server2\c$\Test\Projects.csv"

ProjectID,ProjectName,,Completed

13,Inventory,Redmond,True

440,,FarEast,True

469,Marketing,Europe,False

PS C:\> Import-Csv "\\Server2\c$\Test\Projects.csv"

WARNING: One or more headers were not specified. Default names starting with "H" have been used in place of any missing headers.



ProjectID ProjectName H1      Completed

--------- ----------- --      ---------

13        Inventory   Redmond True

440                   FarEast True

469       Marketing   Europe  False



PS C:\> (Import-Csv "\\Server2\c$\Test\Projects.csv").H1

WARNING: One or more headers were not specified. Default names starting with "H" have been used in place of any missing headers.

Redmond

FarEast

Europe

This example shows how the Import-Csv cmdlet in PowerShell responds when the header row in a CSV file includes a null or empty value.

Import-Csv substitutes a default name for the header row. The default name becomes the name of the property of the object that Import-Csv returns.

The first command uses the Get-Content cmdlet to get the Projects.csv file on the "Server02" remote computer. The output shows that the header row of the file is missing a value between "ProjectName" and "Completed."

The second command uses the Import-Csv cmdlet to import the Projects.csv file.

The output shows that Import-Csv generates a warning and substitutes a default name, "H1", for the missing header row value. "H1" is also used for the name of the object property.

The third command uses the dot method to get the value of the "H1" property of the object that Import-Csv creates.

Required Parameters

Optional Parameters

Inputs

System.String

You can pipe a string that contains a path to Import-Csv .

Outputs

Object

This cmdlet returns the objects described by the content in the CSV file.

Notes

• Because the imported objects are CSV versions of the object type, they are not recognized and formatted by the PowerShell type formatting entries that format the non-CSV versions of the object type.
• The result of an Import-Csv command is a collection of strings that form a table-like custom object. Each row is a separate string, so you can use the Count property of the object to count the table rows. The columns are the properties of the object and items in the rows are the property values.
• The column header row determines the number of columns and the column names. The column names are also the names of the properties of the objects. The first row is interpreted to be the column headers, unless you use the Header parameter to specify column headers. If any row has more values than the header row, the additional values are ignored.
• If the column header row is missing a value or contains a null or empty value, Import-Csv uses "H" followed by a number for the missing column header and property name.
• In the CSV file, each object is represented by a comma-separated list of the property values of the object. The property values are converted to strings (by using the ToString() method of the object), so they are generally represented by the name of the property value. Export-Csv does not export the methods of the object.

Related Links

• ConvertFrom-Csv
• ConvertTo-Csv
• Export-Csv
• Get-Culture