Events
Mar 31, 11 PM - Apr 2, 11 PM
The ultimate Microsoft Fabric, Power BI, SQL, and AI community-led event. March 31 to April 2, 2025.
Register todayThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
This article shows you how to use PowerShell to create and manage directories and files in storage accounts that have a hierarchical namespace.
To learn about how to get, set, and update the access control lists (ACL) of directories and files, see Use PowerShell to manage ACLs in Azure Data Lake Storage.
Reference | Gen1 to Gen2 mapping | Give feedback
An Azure subscription. For more information, see Get Azure free trial.
A storage account that has hierarchical namespace enabled. Follow these instructions to create one.
.NET Framework is 4.7.2 or greater installed. For more information, see Download .NET Framework.
PowerShell version 5.1
or higher.
Verify that the version of PowerShell that 's installed is 5.1
or higher by using the following command.
echo $PSVersionTable.PSVersion.ToString()
To upgrade your version of PowerShell, see Upgrading existing Windows PowerShell
Install Az.Storage module.
Install-Module Az.Storage -Repository PSGallery -Force
For more information about how to install PowerShell modules, see Install the Azure PowerShell module
Open a Windows PowerShell command window, and then sign in to your Azure subscription with the Connect-AzAccount command and follow the on-screen directions.
Connect-AzAccount
If your identity is associated with more than one subscription, and you are not prompted to select the subscription, then set your active subscription to the subscription of the storage account that you want to operate upon. In this example, replace the <subscription-id>
placeholder value with the ID of your subscription.
Select-AzSubscription -SubscriptionId <subscription-id>
Get the storage account context.
$ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -UseConnectedAccount
A container acts as a file system for your files. You can create one by using the New-AzStorageContainer cmdlet.
This example creates a container named my-file-system
.
$filesystemName = "my-file-system"
New-AzStorageContainer -Context $ctx -Name $filesystemName
Create a directory reference by using the New-AzDataLakeGen2Item cmdlet.
This example adds a directory named my-directory
to a container.
$filesystemName = "my-file-system"
$dirname = "my-directory/"
New-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Directory
This example adds the same directory, but also sets the permissions, umask, property values, and metadata values.
$dir = New-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Directory -Permission rwxrwxrwx -Umask ---rwx--- -Property @{"ContentEncoding" = "UDF8"; "CacheControl" = "READ"} -Metadata @{"tag1" = "value1"; "tag2" = "value2" }
This example gets a directory by using the Get-AzDataLakeGen2Item cmdlet, and then prints property values to the console.
$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL
$dir.Permissions
$dir.Group
$dir.Owner
$dir.Properties
$dir.Properties.Metadata
Note
To get the root directory of the container, omit the -Path
parameter.
Rename or move a directory by using the Move-AzDataLakeGen2Item cmdlet.
This example renames a directory from the name my-directory
to the name my-new-directory
.
$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dirname2 = "my-new-directory/"
Move-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -DestFileSystem $filesystemName -DestPath $dirname2
Note
Use the -Force
parameter if you want to overwrite without prompts.
This example moves a directory named my-directory
to a subdirectory of my-directory-2
named my-subdirectory
.
$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dirname2 = "my-directory-2/my-subdirectory/"
Move-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -DestFileSystem $filesystemName -DestPath $dirname2
Delete a directory by using the Remove-AzDataLakeGen2Item cmdlet.
This example deletes a directory named my-directory
.
$filesystemName = "my-file-system"
$dirname = "my-directory/"
Remove-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
You can use the -Force
parameter to remove the file without a prompt.
Download a file from a directory by using the Get-AzDataLakeGen2ItemContent cmdlet.
This example downloads a file named upload.txt
from a directory named my-directory
.
$filesystemName = "my-file-system"
$filePath = "my-directory/upload.txt"
$downloadFilePath = "download.txt"
Get-AzDataLakeGen2ItemContent -Context $ctx -FileSystem $filesystemName -Path $filePath -Destination $downloadFilePath
List the contents of a directory by using the Get-AzDataLakeGen2ChildItem cmdlet. You can use the optional parameter -OutputUserPrincipalName
to get the name (instead of the object ID) of users.
This example lists the contents of a directory named my-directory
.
$filesystemName = "my-file-system"
$dirname = "my-directory/"
Get-AzDataLakeGen2ChildItem -Context $ctx -FileSystem $filesystemName -Path $dirname -OutputUserPrincipalName
The following example lists the ACL
, Permissions
, Group
, and Owner
properties of each item in the directory. The -FetchProperty
parameter is required to get values for the ACL
property.
$filesystemName = "my-file-system"
$dirname = "my-directory/"
$properties = Get-AzDataLakeGen2ChildItem -Context $ctx -FileSystem $filesystemName -Path $dirname -Recurse -FetchProperty
$properties.ACL
$properties.Permissions
$properties.Group
$properties.Owner
Note
To list the contents of the root directory of the container, omit the -Path
parameter.
Upload a file to a directory by using the New-AzDataLakeGen2Item cmdlet.
This example uploads a file named upload.txt
to a directory named my-directory
.
$localSrcFile = "upload.txt"
$filesystemName = "my-file-system"
$dirname = "my-directory/"
$destPath = $dirname + (Get-Item $localSrcFile).Name
New-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $destPath -Source $localSrcFile -Force
This example uploads the same file, but then sets the permissions, umask, property values, and metadata values of the destination file. This example also prints these values to the console.
$file = New-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $destPath -Source $localSrcFile -Permission rwxrwxrwx -Umask ---rwx--- -Property @{"ContentEncoding" = "UDF8"; "CacheControl" = "READ"} -Metadata @{"tag1" = "value1"; "tag2" = "value2" }
$file1
$file1.Properties
$file1.Properties.Metadata
Note
To upload a file to the root directory of the container, omit the -Path
parameter.
This example gets a file by using the Get-AzDataLakeGen2Item cmdlet, and then prints property values to the console.
$filepath = "my-directory/upload.txt"
$filesystemName = "my-file-system"
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filepath
$file
$file.ACL
$file.Permissions
$file.Group
$file.Owner
$file.Properties
$file.Properties.Metadata
Delete a file by using the Remove-AzDataLakeGen2Item cmdlet.
This example deletes a file named upload.txt
.
$filesystemName = "my-file-system"
$filepath = "upload.txt"
Remove-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filepath
You can use the -Force
parameter to remove the file without a prompt.
The following table shows how the cmdlets used for Data Lake Storage Gen1 map to the cmdlets for Data Lake Storage.
Note
Azure Data Lake Storage Gen1 is now retired. See the retirement announcement here. Data Lake Storage Gen1 resources are no longer accessible. If you require special assistance, please contact us.
Data Lake Storage Gen1 cmdlet | Data Lake Storage cmdlet | Notes |
---|---|---|
Get-AzDataLakeStoreChildItem | Get-AzDataLakeGen2ChildItem | By default, the Get-AzDataLakeGen2ChildItem cmdlet only lists the first level child items. The -Recurse parameter lists child items recursively. |
Get-AzDataLakeStoreItem Get-AzDataLakeStoreItemAclEntry Get-AzDataLakeStoreItemOwner Get-AzDataLakeStoreItemPermission |
Get-AzDataLakeGen2Item | The output items of the Get-AzDataLakeGen2Item cmdlet have these properties: Acl, Owner, Group, Permission. |
Get-AzDataLakeStoreItemContent | Get-AzDataLakeGen2FileContent | The Get-AzDataLakeGen2FileContent cmdlet download file content to local file. |
Move-AzDataLakeStoreItem | Move-AzDataLakeGen2Item | |
New-AzDataLakeStoreItem | New-AzDataLakeGen2Item | This cmdlet uploads the new file content from a local file. |
Remove-AzDataLakeStoreItem | Remove-AzDataLakeGen2Item | |
Set-AzDataLakeStoreItemOwner Set-AzDataLakeStoreItemPermission Set-AzDataLakeStoreItemAcl |
Update-AzDataLakeGen2Item | The Update-AzDataLakeGen2Item cmdlet updates a single item only, and not recursively. If you want to update recursively, list items by using the Get-AzDataLakeStoreChildItem cmdlet, then pipeline to the Update-AzDataLakeGen2Item cmdlet. |
Test-AzDataLakeStoreItem | Get-AzDataLakeGen2Item | The Get-AzDataLakeGen2Item cmdlet reports an error if the item doesn't exist. |
Events
Mar 31, 11 PM - Apr 2, 11 PM
The ultimate Microsoft Fabric, Power BI, SQL, and AI community-led event. March 31 to April 2, 2025.
Register todayTraining
Learning path
Large-Scale Data Processing with Azure Data Lake Storage Gen2 - Training
Large-Scale Data Processing with Azure Data Lake Storage Gen2
Certification
Microsoft Certified: Azure Administrator Associate - Certifications
Demonstrate key skills to configure, manage, secure, and administer key professional functions in Microsoft Azure.
Documentation
Use Azure CLI to manage data (Azure Data Lake Storage) - Azure Storage
Use the Azure CLI to manage directories and files in storage accounts that have a hierarchical namespace.
Use Azure Storage Explorer with Azure Data Lake Storage - Azure Storage
Use the Azure Storage Explorer to manage directories and file and directory access control lists (ACL) in storage accounts that has hierarchical namespace (HNS) enabled.
Access control lists in Azure Data Lake Storage - Azure Storage
Understand how POSIX-like ACLs access control lists work in Azure Data Lake Storage.
Work with blob containers from PowerShell - Azure Storage
Learn how to manage Azure storage containers using Azure PowerShell