Select-String

Syntax

Select-String
      [-Culture <String>]
      [-Pattern] <String[]>
      [-Path] <String[]>
      [-SimpleMatch]
      [-CaseSensitive]
      [-Quiet]
      [-List]
      [-NoEmphasis]
      [-Include <String[]>]
      [-Exclude <String[]>]
      [-NotMatch]
      [-AllMatches]
      [-Encoding <Encoding>]
      [-Context <Int32[]>]
      [<CommonParameters>]

Select-String
      [-Culture <String>]
      -InputObject <PSObject>
      [-Pattern] <String[]>
      -Raw
      [-SimpleMatch]
      [-CaseSensitive]
      [-List]
      [-NoEmphasis]
      [-Include <String[]>]
      [-Exclude <String[]>]
      [-NotMatch]
      [-AllMatches]
      [-Encoding <Encoding>]
      [-Context <Int32[]>]
      [<CommonParameters>]

Select-String
      [-Culture <String>]
      -InputObject <PSObject>
      [-Pattern] <String[]>
      [-SimpleMatch]
      [-CaseSensitive]
      [-Quiet]
      [-List]
      [-NoEmphasis]
      [-Include <String[]>]
      [-Exclude <String[]>]
      [-NotMatch]
      [-AllMatches]
      [-Encoding <Encoding>]
      [-Context <Int32[]>]
      [<CommonParameters>]

Select-String
      [-Culture <String>]
      [-Pattern] <String[]>
      [-Path] <String[]>
      -Raw
      [-SimpleMatch]
      [-CaseSensitive]
      [-List]
      [-NoEmphasis]
      [-Include <String[]>]
      [-Exclude <String[]>]
      [-NotMatch]
      [-AllMatches]
      [-Encoding <Encoding>]
      [-Context <Int32[]>]
      [<CommonParameters>]

Select-String
      [-Culture <String>]
      [-Pattern] <String[]>
      -LiteralPath <String[]>
      -Raw
      [-SimpleMatch]
      [-CaseSensitive]
      [-List]
      [-NoEmphasis]
      [-Include <String[]>]
      [-Exclude <String[]>]
      [-NotMatch]
      [-AllMatches]
      [-Encoding <Encoding>]
      [-Context <Int32[]>]
      [<CommonParameters>]

Select-String
      [-Culture <String>]
      [-Pattern] <String[]>
      -LiteralPath <String[]>
      [-SimpleMatch]
      [-CaseSensitive]
      [-Quiet]
      [-List]
      [-NoEmphasis]
      [-Include <String[]>]
      [-Exclude <String[]>]
      [-NotMatch]
      [-AllMatches]
      [-Encoding <Encoding>]
      [-Context <Int32[]>]
      [<CommonParameters>]

Description

The Select-String cmdlet uses regular expression matching to search for text patterns in input strings and files. You can use Select-String similar to grep in UNIX or findstr.exe in Windows.

Select-String is based on lines of text. By default, Select-String finds the first match in each line and, for each match, it displays the file name, line number, and all text in the line containing the match. You can direct Select-String to find multiple matches per line, display text before and after the match, or display a Boolean value (True or False) that indicates whether a match is found.

Select-String can display all the text matches or stop after the first match in each input file. Select-String can be used to display all text that doesn't match the specified pattern.

You can also specify that Select-String should expect a particular character encoding, such as when you're searching files of Unicode text. Select-String uses the byte-order-mark (BOM) to detect the encoding format of the file. If the file has no BOM, it assumes the encoding is UTF8.

Examples

Example 1: Find a case-sensitive match

This example does a case-sensitive match of the text that was sent down the pipeline to the Select-String cmdlet.

'Hello', 'HELLO' | Select-String -Pattern 'HELLO' -CaseSensitive -SimpleMatch

The text strings Hello and HELLO are sent down the pipeline to the Select-String cmdlet. Select-String uses the Pattern parameter to specify HELLO. The CaseSensitive parameter specifies that the case must match only the upper-case pattern. SimpleMatch is an optional parameter and specifies that the string in the pattern isn't interpreted as a regular expression. Select-String displays HELLO in the PowerShell console.

Example 2: Find matches in text files

This command searches all files with the .txt file name extension in the current directory. The output displays the lines in those files that include the specified string.

Get-Alias | Out-File -FilePath .\Alias.txt
Get-Command | Out-File -FilePath .\Command.txt
Select-String -Path .\*.txt -Pattern 'Get-'

Alias.txt:8:Alias            cat -> Get-Content
Alias.txt:28:Alias           dir -> Get-ChildItem
Alias.txt:43:Alias           gal -> Get-Alias
Command.txt:966:Cmdlet       Get-Acl
Command.txt:967:Cmdlet       Get-Alias

In this example, Get-Alias and Get-Command are used with the Out-File cmdlet to create two text files in the current directory, Alias.txt and Command.txt.

Select-String uses the Path parameter with the asterisk (*) wildcard to search all files in the current directory with the file name extension .txt. The Pattern parameter specifies the text to match Get-. Select-String displays the output in the PowerShell console. The file name and line number precede each line of content that contains a match for the Pattern parameter.

Example 3: Find a pattern match

In this example, multiple files are searched to find matches for the specified pattern. The pattern uses a regular expression quantifier. For more information, see about_Regular_Expressions.

Select-String -Path "$PSHOME\en-US\*.txt" -Pattern '\?'

C:\Program Files\PowerShell\6\en-US\default.help.txt:27:    beginning at https://go.microsoft.com/fwlink/?LinkID=108518.
C:\Program Files\PowerShell\6\en-US\default.help.txt:50:    or go to: https://go.microsoft.com/fwlink/?LinkID=210614

The Select-String cmdlet uses two parameters, Path and Pattern. The Path parameter uses the variable $PSHOME that specifies the PowerShell directory. The remainder of the path includes the subdirectory en-US and specifies each *.txt file in the directory. The Pattern parameter specifies to match a question mark (?) in each file. A backslash (\) is used as an escape character and is necessary because the question mark (?) is a regular expression quantifier. Select-String displays the output in the PowerShell console. The file name and line number precede each line of content that contains a match for the Pattern parameter.

Example 4: Use Select-String in a function

This example creates a function to search for a pattern in the PowerShell help files. For this example, the function only exists in the PowerShell session. When the PowerShell session is closed, the function is deleted. For more information, see about_Functions.

function Search-Help
{
    $PSHelp = "$PSHOME\en-US\*.txt"
    Select-String -Path $PSHelp -Pattern 'About_'
}

Search-Help

C:\Program Files\PowerShell\7\en-US\default.help.txt:67:    The titles of conceptual topics begin with "About_".
C:\Program Files\PowerShell\7\en-US\default.help.txt:70:    Get-Help About_<topic-name>
C:\Program Files\PowerShell\7\en-US\default.help.txt:93:    Get-Help About_Modules : Displays help about PowerShell modules.
C:\Program Files\PowerShell\7\en-US\default.help.txt:97:    about_Updatable_Help

The function is created on the PowerShell command line. The Function command uses the name Search-Help. Press Enter to begin adding statements to the function. From the >> prompt, add each statement and press Enter as shown in the example. After the closing bracket is added, you're returned to a PowerShell prompt.

The function contains two commands. The $PSHelp variable stores the path to the PowerShell help files. $PSHOME is the PowerShell installation directory with the subdirectory en-US that specifies each *.txt file in the directory.

The Select-String command in the function uses the Path and Pattern parameters. The Path parameter uses the $PSHelp variable to get the path. The Pattern parameter uses the string About_ as the search criteria.

To run the function, type Search-Help. The function's Select-String command displays the output in the PowerShell console.

Example 5: Search for a string in a Windows event log

This example searches for a string in a Windows event log. The variable $_ represents the current object in the pipeline. For more information, see about_Automatic_Variables.

$Events = Get-WinEvent -LogName Application -MaxEvents 50
$Events | Select-String -InputObject {$_.message} -Pattern 'Failed'

The Get-WinEvent cmdlet uses the LogName parameter to specify the Application log. The MaxEvents parameter gets the 50 most recent events from the log. The log content is stored in the variable named $Events.

The $Events variable is sent down the pipeline to the Select-String cmdlet. Select-String uses the InputObject parameter. The $_ variable represents the current object and message is a property of the event. The Pattern parameter species the string Failed and searches for matches in $_.message. Select-String displays the output in the PowerShell console.

Example 6: Find a string in subdirectories

This example searches a directory and all of its subdirectories for a specific text string.

Get-ChildItem -Path C:\Windows\System32\*.txt -Recurse | Select-String -Pattern 'Microsoft' -CaseSensitive

Get-ChildItem uses the Path parameter to specify C:\Windows\System32*.txt. The Recurse parameter includes the subdirectories. The objects are sent down the pipeline to Select-String.

Select-String uses the Pattern parameter and specifies the string Microsoft. The CaseSensitive parameter is used to match the exact case of the string. Select-String displays the output in the PowerShell console.

Example 7: Find strings that do not match a pattern

This example shows how to exclude lines of data that don't match a pattern.

Get-Command | Out-File -FilePath .\Command.txt
Select-String -Path .\Command.txt -Pattern 'Get', 'Set'  -NotMatch

The Get-Command cmdlet sends objects down the pipeline to the Out-File to create the Command.txt file in the current directory. Select-String uses the Path parameter to specify the Command.txt file. The Pattern parameter specifies Get and Set as the search pattern. The NotMatch parameter excludes Get and Set from the results. Select-String displays the output in the PowerShell console that doesn't include Get or Set.

Example 8: Find lines before and after a match

This example shows how to get the lines before and after the matched pattern.

Get-Command | Out-File -FilePath .\Command.txt
Select-String -Path .\Command.txt -Pattern 'Get-Computer' -Context 2, 3

Command.txt:986:Cmdlet          Get-CmsMessage           6.1.0.0    Microsoft.PowerShell.Security
  Command.txt:987:Cmdlet          Get-Command              6.1.2.0    Microsoft.PowerShell.Core
> Command.txt:988:Cmdlet          Get-ComputerInfo         6.1.0.0    Microsoft.PowerShell.Management
  Command.txt:990:Cmdlet          Get-Content              6.1.0.0    Microsoft.PowerShell.Management
  Command.txt:991:Cmdlet          Get-ControlPanelItem     3.1.0.0    Microsoft.PowerShell.Management
  Command.txt:992:Cmdlet          Get-Credential           6.1.0.0    Microsoft.PowerShell.Security

The Get-Command cmdlet sends objects down the pipeline to the Out-File to create the Command.txt file in the current directory. Select-String uses the Path parameter to specify the Command.txt file. The Pattern parameter specifies Get-Computer as the search pattern. The Context parameter uses two values, before and after, and marks pattern matches in the output with an angle bracket (>). The Context parameter outputs the two lines before the first pattern match and three lines after the last pattern match.

Example 9: Find all pattern matches

This example shows how the AllMatches parameter finds each pattern match in a line of text. By default, Select-String only finds the first occurrence of a pattern in a line of text. This example uses object properties that are found with the Get-Member cmdlet.

$A = Get-ChildItem -Path "$PSHOME\en-US\*.txt" | Select-String -Pattern 'PowerShell'
$A

C:\Program Files\PowerShell\7\en-US\default.help.txt:3:    PowerShell Help System
C:\Program Files\PowerShell\7\en-US\default.help.txt:6:    Displays help about PowerShell cmdlets and concepts.
C:\Program Files\PowerShell\7\en-US\default.help.txt:9:    PowerShell Help describes PowerShell cmdlets

$A.Matches

Groups   : {0}
Success  : True
Name     : 0
Captures : {0}
Index    : 4
Length   : 10
Value    : PowerShell

$A.Matches.Length

8

$B = Get-ChildItem -Path "$PSHOME\en-US\*.txt" | Select-String -Pattern 'PowerShell' -AllMatches
$B.Matches.Length

9

The Get-ChildItem cmdlet uses the Path parameter. The Path parameter uses the variable $PSHOME that specifies the PowerShell directory. The remainder of the path includes the subdirectory en-US and specifies each *.txt file in the directory. The Get-ChildItem objects are stored in the $A variable. The $A variable is sent down the pipeline to the Select-String cmdlet. Select-String uses the Pattern parameter to search each file for the string PowerShell.

From the PowerShell command line, the $A variable contents are displayed. There's a line that contains two occurrences of the string PowerShell.

The $A.Matches property lists the first occurrence of the pattern PowerShell on each line.

The $A.Matches.Length property counts the first occurrence of the pattern PowerShell on each line.

The $B variable uses the same Get-ChildItem and Select-String cmdlets, but adds the AllMatches parameter. AllMatches finds each occurrence of the pattern PowerShell on each line. The objects stored in the $A and $B variables are identical.

The $B.Matches.Length property increases because for each line, every occurrence of the pattern PowerShell is counted.

Example 10 - Convert pipeline objects to strings using `Out-String`

The ToString() result of the piped object isn't the same rich string representation produced by PowerShell's formatting system. So, you may need to pipe the objects to Out-String first.

Piping to Out-String converts the formatted output into a single multi-line string object. This means that when Select-String finds a match it outputs the whole multiline string.

PS> $hash = @{
    Name = 'foo'
    Category = 'bar'
}

# !! NO output, due to .ToString() conversion
$hash | Select-String -Pattern 'foo'

# Out-String converts the output to a single multi-line string object
PS> $hash | Out-String | Select-String -Pattern 'foo'

Name                           Value
----                           -----
Name                           foo
Category                       bar

# Out-String -Stream converts the output to a multiple single-line string objects
PS> $hash | Out-String -Stream | Select-String -Pattern 'foo'

Name                           foo

Piping to Out-String -Stream converts the formatted output into a multiple single-line string objects. This means that when Select-String finds a match it outputs only the matching line.

Parameters

-AllMatches

-CaseSensitive

-Context

-Culture

-Encoding

-Exclude

-Include

-InputObject

-List

-LiteralPath

-NoEmphasis

-NotMatch

-Path

-Pattern

-Quiet

-Raw

-SimpleMatch

Inputs

PSObject

You can pipe any object that has a ToString() method to this cmdlet.

Outputs

MatchInfo

By default, this cmdlet returns a MatchInfo object for each match found.

Boolean

When you use the Quiet parameter, this cmdlet returns a Boolean value indicating whether the pattern was found.

String

When you use the Raw parameter, this cmdlet returns a set of String objects that match the pattern.

Notes

PowerShell includes the following aliases for Select-String:

• All platforms:
  • sls

Select-String is similar to grep in UNIX or findstr.exe in Windows.

The sls alias for the Select-String cmdlet was introduced in PowerShell 3.0.

When piping objects to Select-String:

• FileInfo objects are treated as a path to a file. When file paths are specified, Select-String searches the contents of the file, not the ToString() representation of the object.
• The ToString() result of the piped object isn't the same rich string representation produced by PowerShell's formatting system. So, you may need to pipe the objects to Out-String first. For more information, see Example 10.

To use Select-String, type the text that you want to find as the value of the Pattern parameter. To specify the text to be searched, use the following criteria:

• Type the text in a quoted string, and then pipe it to Select-String.
• Store a text string in a variable, and then specify the variable as the value of the InputObject parameter.
• If the text is stored in files, use the Path parameter to specify the path to the files.

By default, Select-String interprets the value of the Pattern parameter as a regular expression. For more information, see about_Regular_Expressions. You can use the SimpleMatch parameter to override the regular expression matching. The SimpleMatch parameter finds instances of the value of the Pattern parameter in the input.

The default output of Select-String is a MatchInfo object, which includes detailed information about the matches. The information in the object is useful when you're searching for text in files, because MatchInfo objects have properties such as Filename and Line. When the input isn't from the file, the value of these parameters is InputStream.

If you don't need the information in the MatchInfo object, use the Quiet parameter. The Quiet parameter returns a Boolean value (True or False) to indicate whether it found a match, instead of a MatchInfo object.

When matching phrases, Select-String uses the current culture that is set for the system. To find the current culture, use the Get-Culture cmdlet.

To find the properties of a MatchInfo object, type the following command:

Select-String -Path test.txt -Pattern 'test' | Get-Member | Format-List -Property *

Related Links

• about_Automatic_Variables
• about_Comparison_Operators
• about_Functions
• about_Quoting_Rules
• about_Regular_Expressions
• Get-Alias
• Get-ChildItem
• Get-Command
• Get-Member
• Get-WinEvent
• Out-File