New-Item (Microsoft.PowerShell.Management) - PowerShell (2024)

Creates a new item.

Syntax

New-Item [-Path] <String[]> [-ItemType <String>] [-Value <Object>] [-Force] [-Credential <PSCredential>] [-WhatIf] [-Confirm] [<CommonParameters>]

New-Item [[-Path] <String[]>] -Name <String> [-ItemType <String>] [-Value <Object>] [-Force] [-Credential <PSCredential>] [-WhatIf] [-Confirm] [<CommonParameters>]

New-Item [-Path] <string[]> -ConnectionURI <uri> [-ItemType <string>] [-Value <Object>] [-Force] [-Credential <pscredential>] [-WhatIf] [-Confirm] [-OptionSet <hashtable>] [-Authentication <AuthenticationMechanism>] [-CertificateThumbprint <string>] [-SessionOption <SessionOption>] [-Port <int>] [<CommonParameters>]

New-Item [[-Path] <string[]>] -Name <string> [-ItemType <string>] [-Value <Object>] [-Force] [-Credential <pscredential>] [-WhatIf] [-Confirm] [-OptionSet <hashtable>] [-Authentication <AuthenticationMechanism>] [-CertificateThumbprint <string>] [-SessionOption <SessionOption>] [-ApplicationName <string>] [-Port <int>] [-UseSSL] [<CommonParameters>]

New-Item [-Path] <string[]> [-ItemType <string>] [-Value <Object>] [-Force] [-Credential <pscredential>] [-WhatIf] [-Confirm] [-Options <ScopedItemOptions>] [<CommonParameters>]

New-Item [[-Path] <string[]>] -Name <string> [-ItemType <string>] [-Value <Object>] [-Force] [-Credential <pscredential>] [-WhatIf] [-Confirm] [-Options <ScopedItemOptions>] [<CommonParameters>]

Description

The New-Item cmdlet creates a new item and sets its value. The types of items that can be createddepend on the location of the item. For example, in the file system, New-Item creates files andfolders. In the registry, New-Item creates registry keys and entries.

New-Item can also set the value of the items that it creates. For example, when it creates a newfile, New-Item can add initial content to the file.

Examples

Example 1: Create a file in the current directory

This command creates a text file that is named "testfile1.txt" in the current directory. The dot('.') in the value of the Path parameter indicates the current directory. The quoted text thatfollows the Value parameter is added to the file as content.

New-Item -Path . -Name "testfile1.txt" -ItemType "file" -Value "This is a text string."

Example 2: Create a directory

This command creates a directory named "Logfiles" in the C: drive. The ItemType parameterspecifies that the new item is a directory, not a file or other file system object.

New-Item -Path "c:\" -Name "logfiles" -ItemType "directory"

Example 3: Create a profile

This command creates a PowerShell profile in the path that is specified by the $profile variable.

You can use profiles to customize PowerShell. $profile is an automatic (built-in) variable thatstores the path and file name of the "CurrentUser/CurrentHost" profile. By default, the profile doesnot exist, even though PowerShell stores a path and file name for it.

In this command, the $profile variable represents the path of the file. ItemType parameterspecifies that the command creates a file. The Force parameter lets you create a file in theprofile path, even when the directories in the path do not exist.

After you create a profile, you can enter aliases, functions, and scripts in the profile tocustomize your shell.

For more information, see about_Automatic_Variablesand about_Profiles.

New-Item -Path $profile -ItemType "file" -Force

Example 4: Create a directory in a different directory

This example creates a new Scripts directory in the "C:\PS-Test" directory.

The name of the new directory item, "Scripts", is included in the value of Path parameter,instead of being specified in the value of Name. As indicated by the syntax, either command formis valid.

New-Item -ItemType "directory" -Path "c:\ps-test\scripts"

Example 5: Create multiple files

This example creates files in two different directories. Because Path takes multiple strings,you can use it to create multiple items.

New-Item -ItemType "file" -Path "c:\ps-test\test.txt", "c:\ps-test\Logs\test.log"

Example 6: Use wildcards to create files in multiple directories

The New-Item cmdlet supports wildcards in the Path parameter. The following command creates atemp.txt file in all of the directories specified by the wildcards in the Path parameter.

Get-ChildItem -Path C:\Temp\Directory: C:\TempMode LastWriteTime Length Name---- ------------- ------ ----d----- 5/15/2019 6:45 AM 1 Oned----- 5/15/2019 6:45 AM 1 Twod----- 5/15/2019 6:45 AM 1 ThreeNew-Item -Path C:\Temp\* -Name temp.txt -ItemType File | Select-Object FullNameFullName--------C:\Temp\One\temp.txtC:\Temp\Three\temp.txtC:\Temp\Two\temp.txt

The Get-ChildItem cmdlet shows three directories under the C:\Temp directory. Using wildcardsthe New-Item cmdlet creates a temp.txt file in all of the directories under the currentdirectory. The New-Item cmdlet outputs the items you created, which is piped to Select-Objectto verify the paths of the newly created files.

Example 7: Create a symbolic link to a file or folder

This example creates a symbolic link to the Notice.txt file in the current folder.

$link = New-Item -ItemType SymbolicLink -Path .\link -Target .\Notice.txt$link | Select-Object LinkType, TargetLinkType Target-------- ------SymbolicLink {.\Notice.txt}

In this example, Target is an alias for the Value parameter. The target of the symbolic linkcan be a relative path. Prior to PowerShell v6.2, the target must be a fully-qualified path.

Beginning in PowerShell 7.1, you can now create to a SymbolicLink to a folder on Windows using arelative path.

Example 8: Use the -Force parameter to attempt to recreate folders

This example creates a folder with a file inside. Then, attempts to create the same folder using-Force. It will not overwrite the folder but simply return the existing folder object with thefile created intact.

PS> New-Item -Path .\TestFolder -ItemType DirectoryPS> New-Item -Path .\TestFolder\TestFile.txt -ItemType FilePS> New-Item -Path .\TestFolder -ItemType Directory -Force Directory: C:\Mode LastWriteTime Length Name---- ------------- ------ ----d----- 5/1/2020 8:03 AM TestFolderPS> Get-ChildItem .\TestFolder\ Directory: C:\TestFolderMode LastWriteTime Length Name---- ------------- ------ -----a---- 5/1/2020 8:03 AM 0 TestFile.txt

Example 9: Use the -Force parameter to overwrite existing files

This example creates a file with a value and then recreates the file using -Force. This overwritesthe existing file, as you can see by the length property.

PS> New-Item ./TestFile.txt -ItemType File -Value 'This is just a test file' Directory: C:\Source\TestMode LastWriteTime Length Name---- ------------- ------ -----a---- 5/1/2020 8:32 AM 24 TestFile.txtNew-Item ./TestFile.txt -ItemType File -Force Directory: C:\Source\TestMode LastWriteTime Length Name---- ------------- ------ -----a---- 5/1/2020 8:32 AM 0 TestFile.txt

Parameters

-ApplicationName

-Authentication

-CertificateThumbprint

-Confirm

-ConnectionURI

-Credential

-Force

-ItemType

-Name

-Options

-OptionSet

-Path

-Port

-SessionOption

-UseSSL

-Value

-WhatIf

Inputs

Object

You can pipe a value for the new item to this cmdlet.

Outputs

DictionaryEntry

The cmdlet returns a DictionaryEntry object when creating a new environment variable.

DirectoryInfo

The cmdlet returns a DirectoryInfo object when creating a new directory in the filesystem.

FileInfo

The cmdlet returns a FileInfo object when creating a new file in the filesystem.

AliasInfo

The cmdlet returns an AliasInfo object when creating a new alias.

FunctionInfo

The cmdlet returns a FunctionInfo object when creating a new function.

PSVariable

The cmdlet returns a PSVariable object when creating a new variable.

Notes

PowerShell includes the following aliases for New-Item:

• All platforms:
  • ni

New-Item is designed to work with the data exposed by any provider. To list the providersavailable in your session, type Get-PsProvider. For more information, seeabout_Providers.

• Clear-Item
• Copy-Item
• Get-Item
• Invoke-Item
• Move-Item
• Remove-Item
• Rename-Item
• Set-Item
• about_Providers