Version: v5

@capacitor/filesystem

The Filesystem API provides a NodeJS-like API for working with files on the device.

Install

npm install @capacitor/filesystem
npx cap sync

iOS

To have files appear in the Files app, you must set the following keys to YES in Info.plist:

UIFileSharingEnabled (Application supports iTunes file sharing)
LSSupportsOpeningDocumentsInPlace (Supports opening documents in place)

Read about Configuring iOS for help.

Android

If using Directory.Documents or Directory.ExternalStorage, in Android 10 and older, this API requires the following permissions be added to your AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Read about Setting Permissions in the Android Guide for more information on setting Android permissions.

Note that Directory.ExternalStorage is only available on Android 9 or older and Directory.Documents only allows to access the files/foders created by your app on Android on Android 11 and newer.

Working with large files may require you to add android:largeHeap="true" to the <application> tag in AndroidManifest.xml.

Understanding Directories and Files

iOS and Android have additional layers of separation between files, such as special directories that are backed up to the Cloud, or ones for storing Documents. The Filesystem API offers a simple way to scope each operation to a specific special directory on the device.

Additionally, the Filesystem API supports using full file:// paths, or reading content:// files on Android. Simply leave out the directory param to use a full file path.

Example

import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';

const writeSecretFile = async () => {
  await Filesystem.writeFile({
    path: 'secrets/text.txt',
    data: 'This is a test',
    directory: Directory.Documents,
    encoding: Encoding.UTF8,
  });
};

const readSecretFile = async () => {
  const contents = await Filesystem.readFile({
    path: 'secrets/text.txt',
    directory: Directory.Documents,
    encoding: Encoding.UTF8,
  });

  console.log('secrets:', contents);
};

const deleteSecretFile = async () => {
  await Filesystem.deleteFile({
    path: 'secrets/text.txt',
    directory: Directory.Documents,
  });
};

const readFilePath = async () => {
  // Here's an example of reading a file with a full file path. Use this to
  // read binary data (base64 encoded) from plugins that return File URIs, such as
  // the Camera.
  const contents = await Filesystem.readFile({
    path: 'file:///var/mobile/Containers/Data/Application/22A433FD-D82D-4989-8BE6-9FC49DEA20BB/Documents/text.txt',
  });

  console.log('data:', contents);
};

API

readFile(...)
writeFile(...)
appendFile(...)
deleteFile(...)
mkdir(...)
rmdir(...)
readdir(...)
getUri(...)
stat(...)
rename(...)
copy(...)
checkPermissions()
requestPermissions()
downloadFile(...)
addListener('progress', ...)
Interfaces
Type Aliases
Enums

readFile(...)

readFile(options: ReadFileOptions) => Promise<ReadFileResult>

Read a file from disk

Param	Type
`options`	ReadFileOptions

Returns: Promise<ReadFileResult>

Since: 1.0.0

writeFile(...)

writeFile(options: WriteFileOptions) => Promise<WriteFileResult>

Write a file to disk in the specified location on device

Param	Type
`options`	WriteFileOptions

Returns: Promise<WriteFileResult>

Since: 1.0.0

appendFile(...)

appendFile(options: AppendFileOptions) => Promise<void>

Append to a file on disk in the specified location on device

Param	Type
`options`	AppendFileOptions

Since: 1.0.0

deleteFile(...)

deleteFile(options: DeleteFileOptions) => Promise<void>

Delete a file from disk

Param	Type
`options`	DeleteFileOptions

Since: 1.0.0

mkdir(...)

mkdir(options: MkdirOptions) => Promise<void>

Create a directory.

Param	Type
`options`	MkdirOptions

Since: 1.0.0

rmdir(...)

rmdir(options: RmdirOptions) => Promise<void>

Remove a directory

Param	Type
`options`	RmdirOptions

Since: 1.0.0

readdir(...)

readdir(options: ReaddirOptions) => Promise<ReaddirResult>

Return a list of files from the directory (not recursive)

Param	Type
`options`	ReaddirOptions

Returns: Promise<ReaddirResult>

Since: 1.0.0

getUri(...)

getUri(options: GetUriOptions) => Promise<GetUriResult>

Return full File URI for a path and directory

Param	Type
`options`	GetUriOptions

Returns: Promise<GetUriResult>

Since: 1.0.0

stat(...)

stat(options: StatOptions) => Promise<StatResult>

Return data about a file

Param	Type
`options`	StatOptions

Returns: Promise<StatResult>

Since: 1.0.0

rename(...)

rename(options: RenameOptions) => Promise<void>

Rename a file or directory

Param	Type
`options`	CopyOptions

Since: 1.0.0

copy(...)

copy(options: CopyOptions) => Promise<CopyResult>

Copy a file or directory

Param	Type
`options`	CopyOptions

Returns: Promise<CopyResult>

Since: 1.0.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check read/write permissions. Required on Android, only when using Directory.Documents or Directory.ExternalStorage.

Returns: Promise<PermissionStatus>

Since: 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request read/write permissions. Required on Android, only when using Directory.Documents or Directory.ExternalStorage.

Returns: Promise<PermissionStatus>

Since: 1.0.0

downloadFile(...)

downloadFile(options: DownloadFileOptions) => Promise<DownloadFileResult>

Perform a http request to a server and download the file to the specified destination.

Param	Type
`options`	DownloadFileOptions

Returns: Promise<DownloadFileResult>

Since: 5.1.0

addListener('progress', ...)

addListener(eventName: 'progress', listenerFunc: ProgressListener) => Promise<PluginListenerHandle> & PluginListenerHandle

Add a listener to file download progress events.

Param	Type
`eventName`	`'progress'`
`listenerFunc`	ProgressListener

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 5.1.0

Interfaces

ReadFileResult

Prop	Type	Description	Since
`data`	`string \| Blob`	The representation of the data contained in the file Note: Blob is only available on Web. On native, the data is returned as a string.	1.0.0

ReadFileOptions

Prop	Type	Description	Since
`path`	`string`	The path of the file to read	1.0.0
`directory`	Directory	The `Directory` to read the file from	1.0.0
`encoding`	Encoding	The encoding to read the file in, if not provided, data is read as binary and returned as base64 encoded. Pass Encoding.UTF8 to read data as string	1.0.0

WriteFileResult

Prop	Type	Description	Since
`uri`	`string`	The uri where the file was written into	1.0.0

WriteFileOptions

Prop	Type	Description	Default	Since
`path`	`string`	The path of the file to write		1.0.0
`data`	`string \| Blob`	The data to write Note: Blob data is only supported on Web.		1.0.0
`directory`	Directory	The `Directory` to store the file in		1.0.0
`encoding`	Encoding	The encoding to write the file in. If not provided, data is written as base64 encoded. Pass Encoding.UTF8 to write data as string		1.0.0
`recursive`	`boolean`	Whether to create any missing parent directories.	`false`	1.0.0

AppendFileOptions

Prop	Type	Description	Since
`path`	`string`	The path of the file to append	1.0.0
`data`	`string`	The data to write	1.0.0
`directory`	Directory	The `Directory` to store the file in	1.0.0
`encoding`	Encoding	The encoding to write the file in. If not provided, data is written as base64 encoded. Pass Encoding.UTF8 to write data as string	1.0.0

DeleteFileOptions

Prop	Type	Description	Since
`path`	`string`	The path of the file to delete	1.0.0
`directory`	Directory	The `Directory` to delete the file from	1.0.0

MkdirOptions

Prop	Type	Description	Default	Since
`path`	`string`	The path of the new directory		1.0.0
`directory`	Directory	The `Directory` to make the new directory in		1.0.0
`recursive`	`boolean`	Whether to create any missing parent directories as well.	`false`	1.0.0

RmdirOptions

Prop	Type	Description	Default	Since
`path`	`string`	The path of the directory to remove		1.0.0
`directory`	Directory	The `Directory` to remove the directory from		1.0.0
`recursive`	`boolean`	Whether to recursively remove the contents of the directory	`false`	1.0.0

ReaddirResult

Prop	Type	Description	Since
`files`	`FileInfo[]`	List of files and directories inside the directory	1.0.0

FileInfo

Prop	Type	Description	Since
`name`	`string`	Name of the file or directory.
`type`	`'file' \| 'directory'`	Type of the file.	4.0.0
`size`	`number`	Size of the file in bytes.	4.0.0
`ctime`	`number`	Time of creation in milliseconds. It's not available on Android 7 and older devices.	4.0.0
`mtime`	`number`	Time of last modification in milliseconds.	4.0.0
`uri`	`string`	The uri of the file.	4.0.0

ReaddirOptions

Prop	Type	Description	Since
`path`	`string`	The path of the directory to read	1.0.0
`directory`	Directory	The `Directory` to list files from	1.0.0

GetUriResult

Prop	Type	Description	Since
`uri`	`string`	The uri of the file	1.0.0

GetUriOptions

Prop	Type	Description	Since
`path`	`string`	The path of the file to get the URI for	1.0.0
`directory`	Directory	The `Directory` to get the file under	1.0.0

StatResult

Prop	Type	Description	Since
`type`	`'file' \| 'directory'`	Type of the file.	1.0.0
`size`	`number`	Size of the file in bytes.	1.0.0
`ctime`	`number`	Time of creation in milliseconds. It's not available on Android 7 and older devices.	1.0.0
`mtime`	`number`	Time of last modification in milliseconds.	1.0.0
`uri`	`string`	The uri of the file	1.0.0

StatOptions

Prop	Type	Description	Since
`path`	`string`	The path of the file to get data about	1.0.0
`directory`	Directory	The `Directory` to get the file under	1.0.0

CopyOptions

Prop	Type	Description	Since
`from`	`string`	The existing file or directory	1.0.0
`to`	`string`	The destination file or directory	1.0.0
`directory`	Directory	The `Directory` containing the existing file or directory	1.0.0
`toDirectory`	Directory	The `Directory` containing the destination file or directory. If not supplied will use the 'directory' parameter as the destination	1.0.0

CopyResult

Prop	Type	Description	Since
`uri`	`string`	The uri where the file was copied into	4.0.0

PermissionStatus

Prop	Type
`publicStorage`	PermissionState

DownloadFileResult

Prop	Type	Description	Since
`path`	`string`	The path the file was downloaded to.	5.1.0
`blob`	`Blob`	The blob data of the downloaded file. This is only available on web.	5.1.0

DownloadFileOptions

Prop	Type	Description	Default	Since
`path`	`string`	The path the downloaded file should be moved to.		5.1.0
`directory`	Directory	The directory to write the file to. If this option is used, filePath can be a relative path rather than absolute. The default is the `DATA` directory.		5.1.0
`progress`	`boolean`	An optional listener function to receive downloaded progress events. If this option is used, progress event should be dispatched on every chunk received. Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns.		5.1.0
`recursive`	`boolean`	Whether to create any missing parent directories.	`false`	5.1.2

PluginListenerHandle

Prop	Type
`remove`	`() => Promise<void>`

ProgressStatus

Prop	Type	Description	Since
`url`	`string`	The url of the file being downloaded.	5.1.0
`bytes`	`number`	The number of bytes downloaded so far.	5.1.0
`contentLength`	`number`	The total number of bytes to download for this file.	5.1.0

Type Aliases

RenameOptions

CopyOptions

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

ProgressListener

A listener function that receives progress events.

(progress: ProgressStatus): void

Enums

Members	Value	Description	Since
`Documents`	`'DOCUMENTS'`	The Documents directory. On iOS it's the app's documents directory. Use this directory to store user-generated content. On Android it's the Public Documents folder, so it's accessible from other apps. It's not accesible on Android 10 unless the app enables legacy External Storage by adding `android:requestLegacyExternalStorage="true"` in the `application` tag in the `AndroidManifest.xml`. On Android 11 or newer the app can only access the files/folders the app created.	1.0.0
`Data`	`'DATA'`	The Data directory. On iOS it will use the Documents directory. On Android it's the directory holding application files. Files will be deleted when the application is uninstalled.	1.0.0
`Library`	`'LIBRARY'`	The Library directory. On iOS it will use the Library directory. On Android it's the directory holding application files. Files will be deleted when the application is uninstalled.	1.1.0
`Cache`	`'CACHE'`	The Cache directory. Can be deleted in cases of low memory, so use this directory to write app-specific files. that your app can re-create easily.	1.0.0
`External`	`'EXTERNAL'`	The external directory. On iOS it will use the Documents directory. On Android it's the directory on the primary shared/external storage device where the application can place persistent files it owns. These files are internal to the applications, and not typically visible to the user as media. Files will be deleted when the application is uninstalled.	1.0.0
`ExternalStorage`	`'EXTERNAL_STORAGE'`	The external storage directory. On iOS it will use the Documents directory. On Android it's the primary shared/external storage directory. It's not accesible on Android 10 unless the app enables legacy External Storage by adding `android:requestLegacyExternalStorage="true"` in the `application` tag in the `AndroidManifest.xml`. It's not accesible on Android 11 or newer.	1.0.0

Encoding

Members	Value	Description	Since
`UTF8`	`'utf8'`	Eight-bit UCS Transformation Format	1.0.0
`ASCII`	`'ascii'`	Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set This encoding is only supported on Android.	1.0.0
`UTF16`	`'utf16'`	Sixteen-bit UCS Transformation Format, byte order identified by an optional byte-order mark This encoding is only supported on Android.	1.0.0

Install​

iOS​

Android​

Understanding Directories and Files​

Example​

API​

readFile(...)​

writeFile(...)​

appendFile(...)​

deleteFile(...)​

mkdir(...)​

rmdir(...)​

readdir(...)​

getUri(...)​

stat(...)​

rename(...)​

copy(...)​

checkPermissions()​

requestPermissions()​

downloadFile(...)​

addListener('progress', ...)​

Interfaces​

ReadFileResult​

ReadFileOptions​

WriteFileResult​

WriteFileOptions​

AppendFileOptions​

DeleteFileOptions​

MkdirOptions​

RmdirOptions​

ReaddirResult​

FileInfo​

ReaddirOptions​

GetUriResult​

GetUriOptions​

StatResult​

StatOptions​

CopyOptions​

CopyResult​

PermissionStatus​

DownloadFileResult​

DownloadFileOptions​

PluginListenerHandle​

ProgressStatus​

Type Aliases​

RenameOptions​

PermissionState​

ProgressListener​

Enums​

Directory​

Encoding​

Contents

Install

iOS

Android

Understanding Directories and Files

Example

API

readFile(...)

writeFile(...)

appendFile(...)

deleteFile(...)

mkdir(...)

rmdir(...)

readdir(...)

getUri(...)

stat(...)

rename(...)

copy(...)

checkPermissions()

requestPermissions()

downloadFile(...)

addListener('progress', ...)

Interfaces

ReadFileResult

ReadFileOptions

WriteFileResult

WriteFileOptions

AppendFileOptions

DeleteFileOptions

MkdirOptions

RmdirOptions

ReaddirResult

FileInfo

ReaddirOptions

GetUriResult

GetUriOptions

StatResult

StatOptions

CopyOptions

CopyResult

PermissionStatus

DownloadFileResult

DownloadFileOptions

PluginListenerHandle

ProgressStatus

Type Aliases

RenameOptions

PermissionState

ProgressListener

Enums

Directory

Encoding