Edit

Share via

Set-Location

  • Reference
Module:
Microsoft.PowerShell.Management

Sets the current working ___location to a specified ___location.

Syntax

Set-Location
   [[-Path] <String>]
   [-PassThru]
   [<CommonParameters>]
Set-Location
   -LiteralPath <String>
   [-PassThru]
   [<CommonParameters>]
Set-Location
   [-PassThru]
   [-StackName <String>]
   [<CommonParameters>]

Description

The Set-Location cmdlet sets the working ___location to a specified ___location. That ___location could be a directory, a subdirectory, a registry ___location, or any provider path.

PowerShell 6.2 added support for - and + as a values for the Path parameter. PowerShell maintains a history of the last 20 locations that can be accessed with - and +. This list is independent from the ___location stack that is accessed using the StackName parameter.

Examples

Example 1: Set the current ___location

PS C:\> Set-Location -Path "HKLM:\"
PS HKLM:\>

This command sets the current ___location to the root of the HKLM: drive.

Example 2: Set the current ___location and display that ___location

PS C:\> Set-Location -Path "Env:\" -PassThru

Path
----
Env:\

PS Env:\>

This command sets the current ___location to the root of the Env: drive. It uses the PassThru parameter to direct PowerShell to return a PathInfo object that represents the Env:\ ___location.

Example 3: Set ___location to the current ___location in the C: drive

PS C:\Windows\> Set-Location HKLM:\
PS HKLM:\> Set-Location C:
PS C:\Windows\>

The first command sets the ___location to the root of the HKLM: drive in the Registry provider. The second command sets the ___location to the current ___location of the C: drive in the FileSystem provider. When the drive name is specified in the form <DriveName>: (without backslash), the cmdlet sets the ___location to the current ___location in the PSDrive. To get the current ___location in the PSDrive use Get-Location -PSDrive <DriveName> command.

Example 4: Set the current ___location to a named stack

PS C:\> Push-Location -Path 'C:\Program Files\PowerShell\' -StackName "Paths"
PS C:\Program Files\PowerShell\> Set-Location -StackName "Paths"
PS C:\Program Files\PowerShell\> Get-Location -Stack

Path
----
C:\

The first command adds the current ___location to the Paths stack. The second command makes the Paths ___location stack the current ___location stack. The third command displays the locations in the current ___location stack.

The *-Location cmdlets use the current ___location stack unless a different ___location stack is specified in the command. For information about ___location stacks, see the Notes.

Example 5: Navigate ___location history using `+` or `-`

PS C:\> Set-Location -Path $Env:SystemRoot
PS C:\Windows> Set-Location -Path Cert:\
PS Cert:\> Set-Location -Path HKLM:\
PS HKLM:\>

# Navigate back through the history using "-"
PS HKLM:\> Set-Location -Path -
PS Cert:\> Set-Location -Path -
PS C:\Windows>

# Navigate using the Set-Location alias "cd" and the implicit positional Path parameter
PS C:\Windows> cd -
PS C:\> cd +
PS C:\Windows> cd +
PS Cert:\>

Using the alias, cd - or cd + is an easy way to navigate through your ___location history while in your terminal. For more information on navigating with -/+, see the Path parameter.

Parameters

-LiteralPath

Specifies a path of the ___location. The value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcard characters. 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.

Type:String
Aliases:PSPath, LP
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-PassThru

Returns a PathInfo object that represents the ___location. By default, this cmdlet does not generate any output.

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

-Path

Specify the path of a new working ___location. If no path is provided, Set-Location defaults to the current user's home directory. When wildcards are used, the cmdlet chooses the container (directory, registry key, certificate store) that matches the wildcard pattern. If the wildcard pattern matches more than one container, the cmdlet returns an error.

PowerShell keeps a history of the last 20 locations you have set. If the Path parameter value is the - character, then the new working ___location will be the previous working ___location in history (if it exists). Similarly, if the value is the + character, then the new working ___location will be the next working ___location in history (if it exists). This is similar to using Pop-Location and Push-Location except that the history is a list, not a stack, and is implicitly tracked, not manually controlled. There is no way to view the history list.

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

-StackName

Specifies an existing ___location stack name that this cmdlet makes the current ___location stack. Enter a ___location stack name. To indicate the unnamed default ___location stack, type $null or an empty string ("").

Using this parameter does not change the current ___location. It only changes the stack used by the *-Location cmdlets. The *-Location cmdlets act on the current stack unless you use the StackName parameter to specify a different stack. For more information about ___location stacks, see the Notes.

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

Inputs

String

You can pipe a string that contains a path, but not a literal path, to this cmdlet.

Outputs

None

By default, this cmdlet returns no output.

PathInfo

When you use the PassThru parameter with Path or LiteralPath, this cmdlet returns a PathInfo object representing the new ___location.

PathInfoStack

When you use the PassThru parameter with StackName, this cmdlet returns a PathInfoStack object representing the new stack context.

Notes

PowerShell includes the following aliases for Set-Location:

  • All Platforms:
    • cd
    • chdir
    • sl

PowerShell supports multiple runspaces per process. Each runspace has its own current directory. This is not the same as [System.Environment]::CurrentDirectory. This behavior can be an issue when calling .NET APIs or running native applications without providing explicit directory paths.

Even if the ___location cmdlets did set the process-wide current directory, you can't depend on it because another runspace might change it at any time. You should use the ___location cmdlets to perform path-based operations using the current working directory specific to the current runspace.

The Set-Location cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type Get-PSProvider. For more information, see about_Providers.

A stack is a last-in, first-out list in which only the most recently added item can be accessed. You add items to a stack in the order that you use them, and then retrieve them for use in the reverse order. PowerShell lets you store provider locations in ___location stacks. PowerShell creates an unnamed default ___location stack. You can create multiple named ___location stacks. If you do not specify a stack name, PowerShell uses the current ___location stack. By default, the unnamed default ___location is the current ___location stack, but you can use the Set-Location cmdlet to change the current ___location stack.

To manage ___location stacks, use the *-Location cmdlets, as follows:

  • To add a ___location to a ___location stack, use the Push-Location cmdlet.

  • To get a ___location from a ___location stack, use the Pop-Location cmdlet.

  • To display the locations in the current ___location stack, use the Stack parameter of the Get-Location cmdlet. To display the locations in a named ___location stack, use the StackName parameter of Get-Location.

  • To create a new ___location stack, use the StackName parameter of Push-Location. If you specify a stack that does not exist, Push-Location creates the stack.

  • To make a ___location stack the current ___location stack, use the StackName parameter of Set-Location.

The unnamed default ___location stack is fully accessible only when it is the current ___location stack. If you make a named ___location stack the current ___location stack, you can no longer use the Push-Location or Pop-Location cmdlets to add or get items from the default stack or use the Get-Location cmdlet to display the locations in the unnamed stack. To make the unnamed stack the current stack, use the StackName parameter of the Set-Location cmdlet with a value of $null or an empty string ("").