Create a temporary or persistent mapped network drive. (ndr, mount)
Syntax
New-PSDrive [-name] string -PSProvider string [-Persist]
[-root] string [-description string] [-scope string]
[-credential PSCredential] [-WhatIf] [-confirm] [-UseTransaction] [CommonParameters]
Key
-name
The PowerShell drive name to be added.
For persistent mapped drives, use a drive letter e.g. 'h'.
For temporary PowerShell drives, use any valid string e.g. 'windevcluster'.
PowerShell drive names are case-sensitive though name comparisons are not case-sensitive.
-description string
A short description of the drive.
-PSProvider
The name of the provider, if omitted you will be prompted.
e.g. FileSystem, Registry or Certificate.
Mapped network drives can be associated only with the FileSystem provider.
type get-psprovider for a list of providers.
-Persist
Create a mapped network drive. Mapped network drives are persistent, not session-specific, and
can be viewed and managed in File Explorer and other tools. (PowerShell 3.0+)
The name of the drive must be a letter, such as D or E. The value of the Root parameter must
be a UNC path to a different computer. The value of the -PSProvider parameter must be FileSystem.
Mapped network drives are specific to a user account. Mapped drives created in elevated sessions
or sessions using the credential of another user aren’t visible in sessions started using
different credentials. [PowerShell 3.0+ Windows only]
-root string
The data store location that the PowerShell drive will be mapped to.
e.g. a network share (\\Server64\files), a local directory (C:\Programs),
or a registry key (HKLM:\Software\Microsoft).
Temporary PowerShell drives can be associated with a local or remote location on any supported
provider drive. Mapped network drives can be associated only with a file system location
on a remote computer.
-scope
A scope for the drive.
Valid values are "Global", "Local", or "Script", or a number relative
to the current scope (0 through the number of scopes, where 0 is the
current scope and 1 is its parent).
"Local" is the default. For more information, see help about_Scopes.
-credential PSCredential
A user account that has permission to perform this action.
The default is the current user.
a user-name, such as "User01" or "Domain01\User01", or a PSCredential
object, such as the one retrieved by using the Get-Credential cmdlet.
If you type a user name, you will be prompted for a password.
This parameter is not supported by any providers installed with PowerShell.
-whatIf
Describe what would happen if you executed the command without
actually executing the command.
-confirm
Prompt for confirmation before executing the command.
-UseTransaction
Include the command in the active transaction.
Standard Aliases for New-PSDrive: mount, ndr
New-PSDrive creates temporary and persistent drives that are mapped to or associated with a location in a data store, such as a network drive, a directory on the local computer, or a registry key, and persistent Windows mapped network drives that are associated with a file system location on a remote computer.
Mapped drives added using New-PSDrive -persist will be available to other applications such as File Explorer immediately.
Performance: When mapping FileSystem network drives at login, performance can be important. Of the various methods available, New-PSDrive is faster than New-SmbMapping but still slower than NET USE. If the .Net framework has to be loaded, then just starting a PowerShell process can take 2 to 3 seconds. In an already running PowerShell session, NET USE will still map a drive significantly faster, though with only the basic options available.
An Elevated 'admin' process will not be able to see drives mapped under a limited user token and vice versa. This default behaviour can be reversed by setting EnableLinkedConnections, but few organisations will do that due to the potential security risks. Windows File Explorer runs as a non-elevated session.
Temporary PS Drives (i.e. mapped without using the -Persist option) exist only in the current PowerShell session and for the duration of the current user session (until the user closes PowerShell or the drive is removed with Remove-PSDrive).
Temporary PS Drives are not visible to any other applications such as File Explorer, Windows Management Instrumentation (WMI), Component Object Model (COM), Microsoft .NET Framework, or to tools such as NET USE or Get-CIMinstance Win32_NetworkConnection
Temporary PS Drives can have any name that is valid in PowerShell and can be mapped to any local or remote resource. You can use temporary PowerShell drives to access data in the associated data store, just as you would do with any mapped network drive. You can change locations into the drive, by using Set-Location, and access the contents of the drive by using Get-Item or Get-ChildItem.
If a Temporary PS Drive is created with a name that is the same an an existing File System drive mapping e.g. H: mapped with NET USE, then it will temporarily replace that drive mapping within the PowerShell session. If the PSDrive is later removed then H: will automatically revert to its previous mapping.
Temporary PS Drives can be given a one letter name like traditional drive mappings, but there is no reason not to select a longer more descriptive name as they are not visible outside PowerShell anyway.
Temporary PS Drives are not inherited by any sub-shell or process that you open.
The following features were added to New-PSDrive in PowerShell 3.0:
- Mapped network drives. You can use the Persist parameter of New-PSDrive to create Windows mapped network drives. Unlike temporary PowerShell drives, Windows mapped network drives aren’t session-specific. They're saved in Windows and they can be managed by using standard Windows tools, such as File Explorer and net use. Mapped network drives must have a drive-letter name and be connected to a remote file system location.
If your command is scoped locally, not dot-sourced, the -Persist parameter will not persist the creation of a PSDrive beyond the scope in which the command is running. If you're running New-PSDrive inside a script, and you want the drive to persist indefinitely, you must dot-source the script.
For best results, to force a new drive to persist indefinitely, add the -Scope parameter to your command, and set its value to Global.- External drives. When an external drive is connected to the computer, PowerShell automatically adds a PSDrive to the file system that represents the new drive. You don’t have to restart PowerShell. Similarly, when an external drive is disconnected from the computer, PowerShell automatically deletes the PSDrive that represents the removed drive.
- Credentials for Universal Naming Convention (UNC) paths.
PSDrives are created in the scope in which the New-PSDrive command is run. When a New-PSDrive command is run within a script, the drive mapping is local to the script. To ensure that the drive is available after the script has completed, use the -Scope parameter and create the drive in the Global scope. Both Temporary and Persistent drives can be mapped using a script.
To disconnect a mapped network drive, use Remove-PSDrive. When you disconnect a mapped network drive, the mapping is permanently deleted from the computer, not just deleted from the current session. Mapped network drives are specific to a user account. Mapped network drives that you create in sessions that are started with the "Run as administrator" option or with the credential of another user are not visible in a session that started without explicit credentials or with the credentials of the current user.
When the value of the Root parameter is a UNC path, such as \\Server\Share, the credential specified in the value of the Credential parameter is used to create the PSDrive. Otherwise, Credential isn’t effective when you're creating new file system drives.
Install a drive called 'windevcluster' using the file system provider. The drive will be rooted at "C:\MyDocs":
PS C:\> New-PSDrive -name windevcluster -psProvider FileSystem -root C:\MyDocs -persist -scope global
Get-ChildItem windevcluster:
Install a drive called 'S:' using the file system provider. The drive will be rooted at \\Server64\teams:
PS C:\> New-PSDrive -name S -PsProvider FileSystem -root \\Server64\teams -persist -scope global
S:
PS S:\> Get-ChildItem S:
The parameters are positional, so:
PS C:\> New-PSDrive -name M -psprovider FileSystem -root \\Server\Share
is the same as:
PS C:\> New-PSDrive M FileSystem \\Server\Share
Map a drive S: but only if the remote server is available:
$shared = "\\Server64\teams"
if (Test-Connection $shared -Quiet) {
New-PSDrive -Name "S" -PSProvider FileSystem -Root $shared -Persist -scope global
}else{
Remove-PsDrive -Name "S"
}
“If the automobile had followed the same development cycle as the computer, a Rolls-Royce would today cost $100, get a million miles per gallon, and explode once a year, killing everyone inside” ~ Robert X. Cringely, InfoWorld
New-SmbMapping - Map to an SMB share.
Get-PSDrive - Get drive information (DriveInfo).
Remove-PSDrive - Remove a provider/drive from its location.
Get-Command - Retrieve basic information about a command.
Get-Member - Enumerate the properties of an object.
Equivalent bash command: mount - Mount a file system.