Skip to main content
SysAdmin Shell Scripting Essentials

PowerShell Create a Directory: New-Item and mkdir Syntax & Error

4 min read

powershell create a directory is the task of creating a filesystem folder using PowerShell’s New-Item cmdlet or its built-in mkdir alias. It requires at minimum a path and -ItemType Directory.

New-Item -Path 'D:tempTest Folder' -ItemType Directory

Overview

New-Item -ItemType Directory is the canonical method for folder creation. The mkdir alias maps to the same cmdlet, but the full form exposes parameters like -Name (separate folder name from parent path), -Force (suppress errors if directory already exists), and -WhatIf (preview without executing). The cmdlet returns a DirectoryInfo object on success.

Syntax

# Default parameter set: Path
New-Item [-Path]  [-ItemType]  [[-Value] ] [-Force] [-Credential ] [-WhatIf] [-Confirm] []

# Using Name parameter
New-Item [[-Path] ] [-Name]  [-ItemType]  [[-Value] ] [-Force] [-Credential ] [-WhatIf] [-Confirm] []

# mkdir alias (equivalent to New-Item -ItemType Directory)
mkdir 

Parameters






Parameter
Type
Description






-Path
String[]
Specifies the destination path. Accepts one or more paths. The entire path must exist except the final component.




-Name
String
Specifies the folder name separately from the parent directory. Allows creating a folder in a location without building the full path.




-ItemType
String
For directories, use Directory. Also supports File, SymbolicLink, Junction, and others.




-Value
Object
Ignored for directories. Used only for files or registry keys.




-Force
Switch
Suppresses errors if the target already exists. Does not create missing parent directories. If a parent path component is missing, the command fails.




-WhatIf
Switch
Shows what would happen without executing. Useful for dry-run testing.




-Confirm
Switch
Prompts for confirmation before executing.




-Credential
PSCredential
Alternate credentials for the operation (rarely used for filesystem).






Usage Examples


Example 1: Single directory


New-Item -Path "C:ProjectsLogs" -ItemType Directory


Creates Logs under C:Projects. Fails with Cannot find path if C:Projects does not exist. Returns a DirectoryInfo object.


Example 2: Idempotent creation with existence check


$path = "C:DataReportsQ1"
if (-not (Test-Path -Path $path)) {
    New-Item -Path $path -ItemType Directory -Force | Out-Null
}


Tests for the directory first, then creates only if missing. The -Force handles race conditions if another process creates the directory between the test and creation. Redirecting output to $null suppresses the DirectoryInfo object in scripts.


Example 3: Loop over multiple projects


$projects = @("ProjectA", "ProjectB", "ProjectC")
$base = "\servershareBuilds"
foreach ($proj in $projects) {
    New-Item -Path "$base$projLogs" -ItemType Directory -ErrorAction SilentlyContinue | Out-Null
}


Creates a Logs subfolder under each project. -ErrorAction SilentlyContinue skips already-existing folders without terminating the loop. Ideal for CI/CD agent scripts.


Troubleshooting Common Errors






Error
Cause
Solution






Cannot find path '...' because it does not exist.
Parent directory is missing.
Create each parent separately or use a script to iterate up the path. -Force does not create parents.




Access to the path '...' is denied.
Insufficient write permissions.
Run PowerShell as Administrator or adjust ACLs with icacls. For network shares, verify share and NTFS permissions.




The given path's format is not supported.
Path too long (>260 chars) or invalid characters.
Use extended-length prefix \? on Windows 10 1607+ and PowerShell 5.1+. Ensure no illegal characters like |, ?, *.




A parameter cannot be found that matches parameter name 'Type'.
Used -Type instead of -ItemType.
Use -ItemType Directory.






Cmdlet Behavior Notes


    

  • Return type: DirectoryInfo for filesystem directories.
    • 

  • Error action: Non-existent parent path throws a terminating error (ObjectNotFound). Access denied throws a non-terminating error (UnauthorizedAccessException).
    • 

  • Idempotency: -Force only suppresses the “already exists” error; it does not overwrite or modify the directory.
    • 

  • Cross-platform: On PowerShell 7+, the cmdlet works identically on Linux and macOS using forward slashes. The -Credential parameter is not supported on non-Windows platforms.
    • 

  • Version note: Beginning in PowerShell 7.1, New-Item -ItemType SymbolicLink can target a folder using a relative path on Windows. On Windows PowerShell 5.1, symbolic links require absolute paths.
    • 



Frequently Asked Questions




What is the difference between New-Item -ItemType Directory and the md/mkdir aliases?


Answer: New-Item -ItemType Directory is the official cmdlet; md and mkdir are built-in aliases that call the exact same cmdlet. All three accept the same parameters and return the same object. Use the alias for speed in interactive sessions, and the full cmdlet for script clarity.


# These are functionally identical
New-Item -ItemType Directory -Path 'D:logs'
md 'D:logs'
mkdir 'D:logs'






Does -Force create parent directories?


Answer: No. -Force only suppresses the error that occurs if the target directory already exists. It never creates intermediate directories. If you specify a path like C:parentchild and C:parent is missing, the command fails regardless of -Force.


# This fails even with -Force if C:parent does not exist
New-Item -ItemType Directory -Path 'C:parentchild' -Force






How do I create a directory with all parent directories in one command?


Answer: PowerShell has no built-in equivalent of mkdir -p in Unix. You must create each missing parent manually or use a helper function:


function New-DirectoryTree {
    param([string]$Path)
    $parent = Split-Path $Path -Parent
    if (-not (Test-Path $parent)) {
        New-DirectoryTree $parent
    }
    New-Item -ItemType Directory -Path $Path -Force | Out-Null
}
New-DirectoryTree -Path 'C:abc'






How do I resolve “Access to the path is denied”?


Answer: Launch PowerShell with “Run as Administrator” for system folders. For network shares, ensure both share and NTFS permissions grant Modify/Write. Use icacls to inspect or adjust permissions:


# Check permissions
icacls 'C:target'
# Grant current user write access (run in elevated session)
icacls 'C:target' /grant "$env:USERNAME:(CI)(OI)(W)"






Does New-Item -ItemType Directory work on Linux or macOS?


Answer: Yes, on PowerShell Core 6+ (cross-platform). Use forward slashes and note that the -Credential parameter is not supported on non-Windows. File permissions follow the OS defaults.


# Works on Linux/macOS
New-Item -ItemType Directory -Path '/var/log/myapp' -Force





See also  Powershell Updates — Verified Syntax, Flags & Troubleshooting