File access permissions

Universal Windows Platform (UWP) apps can access certain file system locations by default. Apps can also access additional locations through the file picker, or by declaring capabilities.

Locations that all apps can access

When you create a new app, you can access the following file system locations by default:

Application install directory

The folder where your app is installed on the user’s system.

There are two primary ways to access files and folders in your app’s install directory:

You can retrieve a StorageFolder that represents your app’s install directory, like this:

You can then access files and folders in the directory using StorageFolder methods. In the example, this StorageFolder is stored in the installDirectory variable. You can learn more about working with your app package and install directory from the App package information sample on GitHub.

You can retrieve a file directly from your app’s install directory by using an app URI, like this:

When GetFileFromApplicationUriAsync completes, it returns a StorageFile that represents the file.txt file in the app’s install directory ( file in the example).

The «ms-appx:///» prefix in the URI refers to the app’s install directory. You can learn more about using app URIs in How to use URIs to reference content.

In addition, and unlike other locations, you can also access files in your app install directory by using some Win32 and COM for Universal Windows Platform (UWP) apps and some C/C++ Standard Library functions from Microsoft Visual Studio.

The app’s install directory is a read-only location. You can’t gain access to the install directory through the file picker.

Application data locations

The folders where your app can store data. These folders (local, roaming and temporary) are created when your app is installed.

There are two primary ways to access files and folders from your app’s data locations:

Use ApplicationData properties to retrieve an app data folder.

For example, you can use ApplicationData.LocalFolder to retrieve a StorageFolder that represents your app’s local folder like this:

If you want to access your app’s roaming or temporary folder, use the RoamingFolder or TemporaryFolder property instead.

After you retrieve a StorageFolder that represents an app data location, you can access files and folders in that location by using StorageFolder methods. In the example, these StorageFolder objects are stored in the localFolder variable. You can learn more about using app data locations from the guidance on the ApplicationData class page, and by downloading the Application data sample from GitHub.

You can retrieve a file directly from your app’s local folder by using an app URI, like this:

When GetFileFromApplicationUriAsync completes, it returns a StorageFile that represents the file.txt file in the app’s local folder ( file in the example).

The «ms-appdata:///local/» prefix in the URI refers to the app’s local folder. To access files in the app’s roaming or temporary folders use «ms-appdata:///roaming/» or «ms-appdata:///temporary/» instead. You can learn more about using app URIs in How to load file resources.

In addition, and unlike other locations, you can also access files in your app data locations by using some Win32 and COM for UWP apps and some C/C++ Standard Library functions from Visual Studio.

You can’t access the local, roaming, or temporary folders through the file picker.

Removable devices

Additionally, your app can access some of the files on connected devices by default. This is an option if your app uses the AutoPlay extension to launch automatically when users connect a device, like a camera or USB thumb drive, to their system. The files your app can access are limited to specific file types that are specified via File Type Association declarations in your app manifest.

Of course, you can also gain access to files and folders on a removable device by calling the file picker (using FileOpenPicker and FolderPicker) and letting the user pick files and folders for your app to access. Learn how to use the file picker in Open files and folders with a picker.

For more info about accessing an SD card or other removable devices, see Access the SD card.

Locations that UWP apps can access

User’s Downloads folder

The folder where downloaded files are saved by default.

By default, your app can only access files and folders in the user’s Downloads folder that your app created. However, you can gain access to files and folders in the user’s Downloads folder by calling a file picker (FileOpenPicker or FolderPicker) so that users can navigate and pick files or folders for your app to access.

You can create a file in the user’s Downloads folder like this:

DownloadsFolder.CreateFileAsync is overloaded so that you can specify what the system should do if there is already an existing file in the Downloads folder that has the same name. When these methods complete, they return a StorageFile that represents the file that was created. This file is called newFile in the example.

You can create a subfolder in the user’s Downloads folder like this:

DownloadsFolder.CreateFolderAsync is overloaded so that you can specify what the system should do if there is already an existing subfolder in the Downloads folder that has the same name. When these methods complete, they return a StorageFolder that represents the subfolder that was created. This file is called newFolder in the example.

Accessing additional locations

In addition to the default locations, an app can access additional files and folders by declaring capabilities in the app manifest or by calling a file picker to let the user pick files and folders for the app to access.

Apps that declare the AppExecutionAlias extension have file-system permissions from the directory that they are launched from in the console window, and downwards.

Retaining access to files and folders

When your app retrieves a file or folder via a picker, a file activation, a drag-and-drop operation, etc. it only has access to that file or folder until the app is terminated. If you would like to automatically access the file or folder in the future, you can add it to the FutureAccessList so that your app can readily access that item in the future. You can also use the MostRecentlyUsedList to easily manage a list of recently-used files.

Capabilities for accessing other locations

The following table lists additional locations that you can access by declaring one or more capabilities and using the associated Windows.Storage API.

Location	Capability	Windows.Storage API
All files that the user has access to. For example: documents, pictures, photos, downloads, desktop, OneDrive, etc.	broadFileSystemAccess This is a restricted capability. Access is configurable in Settings > Privacy > File system. Because users can grant or deny the permission any time in Settings, you should ensure that your app is resilient to those changes. If you find that your app does not have access, you may choose to prompt the user to change the setting by providing a link to the Windows 10 file system access and privacy article. Note that the user must close the app, toggle the setting, and restart the app. If they toggle the setting while the app is running, the platform will suspend your app so that you can save the state, then forcibly terminate the app in order to apply the new setting. In the April 2018 update, the default for the permission is On. In the October 2018 update, the default is Off. If you submit an app to the Store that declares this capability, you will need to supply additional descriptions of why your app needs this capability, and how it intends to use it. This capability works for APIs in the Windows.Storage namespace. See the Example section at the end of this article for an example of how to enable this capability in your app. Note: This capability is not supported on Xbox.	n/a
Documents	documentsLibrary Note: You must add File Type Associations to your app manifest that declare specific file types that your app can access in this location. Use this capability if your app: — Facilitates cross-platform offline access to specific OneDrive content using valid OneDrive URLs or Resource IDs — Saves open files to the user’s OneDrive automatically while offline	KnownFolders.DocumentsLibrary
Music	musicLibrary Also see Files and folders in the Music, Pictures, and Videos libraries.	KnownFolders.MusicLibrary
Pictures	picturesLibrary Also see Files and folders in the Music, Pictures, and Videos libraries.	KnownFolders.PicturesLibrary
Videos	videosLibrary Also see Files and folders in the Music, Pictures, and Videos libraries.	KnownFolders.VideosLibrary
Removable devices	removableStorage Note You must add File Type Associations to your app manifest that declare specific file types that your app can access in this location. Also see Access the SD card.	KnownFolders.RemovableDevices
Homegroup libraries	At least one of the following capabilities is needed. — musicLibrary — picturesLibrary — videosLibrary	KnownFolders.HomeGroup
Media server devices (DLNA)	At least one of the following capabilities is needed. — musicLibrary — picturesLibrary — videosLibrary	KnownFolders.MediaServerDevices
Universal Naming Convention (UNC) folders	A combination of the following capabilities is needed. The home and work networks capability: — privateNetworkClientServer And at least one internet and public networks capability: — internetClient — internetClientServer And, if applicable, the domain credentials capability: — enterpriseAuthentication Note: You must add File Type Associations to your app manifest that declare specific file types that your app can access in this location.	Retrieve a folder using: StorageFolder.GetFolderFromPathAsync Retrieve a file using: StorageFile.GetFileFromPathAsync

Example

This example adds the restricted broadFileSystemAccess capability. In addition to specifying the capability, the rescap namespace must be added, and is also added to IgnorableNamespaces .

For a complete list of app capabilities, see App capability declarations.

File Permissions for WSL

This page details how Linux file permissions are interpreted across the Windows Subsystem for Linux, especially when accessing resources inside of Windows on the NT file system. This documentation assumes a basic understanding of the Linux file system permissions structure and the umask command.

When accessing Windows files from WSL the file permissions are either calculated from Windows permissions, or are read from metadata that has been added to the file by WSL. This metadata is not enabled by default.

WSL metadata on Windows files

When metadata is enabled as a mount option in WSL, extended attributes on Windows NT files can be added and interpreted to supply Linux file system permissions.

WSL can add four NTFS extended attributes:

Attribute Name	Description
$LXUID	User Owner ID
$LXGID	Group Owner ID
$LXMOD	File mode (File systems permission octals and type, e.g: 0777)
$LXDEV	Device, if it is a device file

Additionally, any file that is not a regular file or directory (e.g: symlinks, FIFOs, block devices, unix sockets, and character devices) also have an NTFS reparse point. This makes it much faster to determine the kind of file in a given directory without having to query its extended attributes.

File Access Scenarios

Below is a description of how permissions are determined when accessing files in different ways using the Windows Subsystem for Linux.

Accessing Files in the Windows drive file system (DrvFS) from Linux

These scenarios occur when you are accessing your Windows files from WSL, most likely via /mnt/c .

Reading file permissions from an existing Windows file

The result depends on if the file already has existing metadata.

DrvFS file does not have metadata (default)

If the file has no metadata associated with it then we translate the effective permissions of the Windows user to read/write/execute bits and set them to the this as the same value for user, group, and other. For example, if your Windows user account has read and execute access but not write access to the file then this will be shown as r-x for user, group and other. If the file has the ‘Read Only’ attribute set in Windows then we do not grant write access in Linux.

The file has metadata

If the file has metadata present, we simply use those metadata values instead of translating effective permissions of the Windows user.

Changing file permissions on an existing Windows file using chmod

The result depends on if the file already has existing metadata.

chmod file does not have metadata (default)

Chmod will only have one effect, if you remove all the write attributes of a file then the ‘read only’ attribute on the Windows file will be set, since this is the same behaviour as CIFS (Common Internet File System) which is the SMB (Server Message Block) client in Linux.

chmod file has metadata

Chmod will change or add metadata depending on the file’s already existing metadata.

Please keep in mind that you cannot give yourself more access than what you have on Windows, even if the metadata says that is the case. For example, you could set the metadata to display that you have write permissions to a file using chmod 777 , but if you tried to access that file you would still not be able to write to it. This is thanks to interopability, as any read or write commands to Windows files are routed through your Windows user permissions.

Creating a file in DriveFS

The result depends on if metadata is enabled.

Metadata is not enabled (default)

The Windows permissions of the newly created file will be the same as if you created the file in Windows without a specific security descriptor, it will inherit the parent’s permissions.

Metadata is enabled

The file’s permission bits are set to follow the Linux umask, and the file will be saved with metadata.

Which Linux user and Linux group owns the file?

The result depends on if the file already has existing metadata.

User file does not have metadata (default)

In the default scenario, when automounting Windows drives, we specify that the user ID (UID) for any file is set to the user ID of your WSL user and the group ID (GID) is set to the principal group ID of your WSL user.

User file has metadata

The UID and GID specified in the metadata is applied as the user owner and group owner of the file.

Accessing Linux files from Windows using \\wsl$

Accessing Linux files via \\wsl$ will use the default user of your WSL distribution. Therefore any Windows app accessing Linux files will have the same permissions as the default user.

Creating a new file

The default umask is applied when creating a new file inside of a WSL distribution from Windows. The default umask is 022 , or in other words it allows all permissions except write permissions to groups and others.

Accessing files in the Linux root file system from Linux

Any files created, modified, or accessed in the Linux root file system follow standard Linux conventions, such as applying the umask to a newly created file.

Configuring file permissions

You can configure your file permissions inside of your Windows drives using the mount options in wsl.conf. The mount options allow you to set umask , dmask and fmask permissions masks. The umask is applied to all files, the dmask is applied just to directories and the fmask is applied just to files. These permission masks are then put through a logical OR operation when being applied to files, e.g: If you have a umask value of 023 and an fmask value of 022 then the resulting permissions mask for files will be 023 .

Please see the Configure per distro launch settings with wslconf article for instructions on how to do this.