Skip to main content
Version: v7

@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

Apple Privacy Manifest Requirements​

Apple mandates that app developers now specify approved reasons for API usage to enhance user privacy. By May 1st, 2024, it's required to include these reasons when submitting apps to the App Store Connect.

When using this specific plugin in your app, you must create a PrivacyInfo.xcprivacy file in /ios/App or use the VS Code Extension to generate it, specifying the usage reasons.

For detailed steps on how to do this, please see the Capacitor Docs.

For this plugin, the required dictionary key is NSPrivacyAccessedAPICategoryFileTimestamp and the recommended reason is C617.1.

Example PrivacyInfo.xcprivacy​

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>NSPrivacyAccessedAPITypes</key>
<array>
<!-- Add this dict entry to the array if the PrivacyInfo file already exists -->
<dict>
<key>NSPrivacyAccessedAPIType</key>
<string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
<key>NSPrivacyAccessedAPITypeReasons</key>
<array>
<string>C617.1</string>
</array>
</dict>
</array>
</dict>
</plist>

Migrating from downloadFile to File Transfer plugin​

As of version 7.1.0, the downloadFile functionality in the Filesystem plugin has been deprecated in favor of the new @capacitor/file-transfer plugin.

Installing the File Transfer plugin​

npm install @capacitor/file-transfer
npx cap sync

Migration example​

Before (using Filesystem plugin):

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

await Filesystem.downloadFile({
url: 'https://example.com/file.pdf',
path: 'downloaded-file.pdf',
directory: Directory.Documents,
progress: true
});

// Progress events
Filesystem.addListener('progress', (progress) => {
console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`);
});

After (using File Transfer plugin):

import { FileTransfer } from '@capacitor/file-transfer';
import { Filesystem, Directory } from '@capacitor/filesystem';

// First get the full file path using Filesystem
const fileInfo = await Filesystem.getUri({
directory: Directory.Documents,
path: 'downloaded-file.pdf'
});

// Then use the FileTransfer plugin to download
await FileTransfer.downloadFile({
url: 'https://example.com/file.pdf',
path: fileInfo.uri,
progress: true
});

// Progress events
FileTransfer.addListener('progress', (progress) => {
console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`);
});

The File Transfer plugin offers improved reliability, better error handling with specific error codes, and also adds upload functionality.

iOS​

To have files appear in the Files app, you must also 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/folders 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​

For list of existing error codes, see Errors.

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


readFile(...)​

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

Read a file from disk

ParamType
options
ReadFileOptions

Returns:

Promise<ReadFileResult>

Since: 1.0.0


readFileInChunks(...)​

readFileInChunks(options: ReadFileInChunksOptions, callback: ReadFileInChunksCallback) => Promise<CallbackID>

Read a file from disk, in chunks. Native only (not available in web). Use the callback to receive each read chunk. If empty chunk is returned, it means file has been completely read.

ParamType
options
ReadFileInChunksOptions
callback
ReadFileInChunksCallback

Returns: Promise<string>

Since: 7.1.0


writeFile(...)​

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

Write a file to disk in the specified location on device

ParamType
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

ParamType
options
AppendFileOptions

Since: 1.0.0


deleteFile(...)​

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

Delete a file from disk

ParamType
options
DeleteFileOptions

Since: 1.0.0


mkdir(...)​

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

Create a directory.

ParamType
options
MkdirOptions

Since: 1.0.0


rmdir(...)​

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

Remove a directory

ParamType
options
RmdirOptions

Since: 1.0.0


readdir(...)​

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

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

ParamType
options
ReaddirOptions

Returns:

Promise<ReaddirResult>

Since: 1.0.0


getUri(...)​

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

Return full File URI for a path and directory

ParamType
options
GetUriOptions

Returns:

Promise<GetUriResult>

Since: 1.0.0


stat(...)​

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

Return data about a file

ParamType
options
StatOptions

Returns:

Promise<FileInfo>

Since: 1.0.0


rename(...)​

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

Rename a file or directory

ParamType
options
CopyOptions

Since: 1.0.0


copy(...)​

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

Copy a file or directory

ParamType
options
CopyOptions

Returns:

Promise<CopyResult>

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.

This method has been deprecated since version 7.1.0. We recommend using the @capacitor/file-transfer plugin instead, in conjunction with this plugin.

ParamType
options
DownloadFileOptions

Returns:

Promise<DownloadFileResult>

Since: 5.1.0


addListener('progress', ...)​

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

Add a listener to file download progress events.

This method has been deprecated since version 7.1.0. We recommend using the @capacitor/file-transfer plugin instead, in conjunction with this plugin.

ParamType
eventName'progress'
listenerFunc
ProgressListener

Returns:

Promise<PluginListenerHandle>

Since: 5.1.0


removeAllListeners()​

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

This method has been deprecated since version 7.1.0. We recommend using the @capacitor/file-transfer plugin instead, in conjunction with this plugin.

Since: 5.2.0


Interfaces​

PermissionStatus​

PropType
publicStorage
PermissionState

ReadFileResult​

PropTypeDescriptionSince
datastring | BlobThe 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​

PropTypeDescriptionSince
pathstringThe path of the file to read1.0.0
directory
Directory
The Directory to read the file from1.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 string1.0.0

ReadFileInChunksOptions​

PropTypeDescriptionSince
chunkSizenumberSize of the chunks in bytes.7.1.0

WriteFileResult​

PropTypeDescriptionSince
uristringThe uri where the file was written into1.0.0

WriteFileOptions​

PropTypeDescriptionDefaultSince
pathstringThe path of the file to write1.0.0
datastring | BlobThe data to write Note: Blob data is only supported on Web.1.0.0
directory
Directory
The Directory to store the file in1.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 string1.0.0
recursivebooleanWhether to create any missing parent directories.false1.0.0

AppendFileOptions​

PropTypeDescriptionSince
pathstringThe path of the file to append1.0.0
datastringThe data to write1.0.0
directory
Directory
The Directory to store the file in1.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 string1.0.0

DeleteFileOptions​

PropTypeDescriptionSince
pathstringThe path of the file to delete1.0.0
directory
Directory
The Directory to delete the file from1.0.0

MkdirOptions​

PropTypeDescriptionDefaultSince
pathstringThe path of the new directory1.0.0
directory
Directory
The Directory to make the new directory in1.0.0
recursivebooleanWhether to create any missing parent directories as well.false1.0.0

RmdirOptions​

PropTypeDescriptionDefaultSince
pathstringThe path of the directory to remove1.0.0
directory
Directory
The Directory to remove the directory from1.0.0
recursivebooleanWhether to recursively remove the contents of the directoryfalse1.0.0

ReaddirResult​

PropTypeDescriptionSince
filesFileInfo[]List of files and directories inside the directory1.0.0

FileInfo​

PropTypeDescriptionSince
namestringName of the file or directory.7.1.0
type'file' | 'directory'Type of the file.4.0.0
sizenumberSize of the file in bytes.4.0.0
ctimenumberTime of creation in milliseconds. It's not available on Android 7 and older devices.7.1.0
mtimenumberTime of last modification in milliseconds.7.1.0
uristringThe uri of the file.4.0.0

ReaddirOptions​

PropTypeDescriptionSince
pathstringThe path of the directory to read1.0.0
directory
Directory
The Directory to list files from1.0.0

GetUriResult​

PropTypeDescriptionSince
uristringThe uri of the file1.0.0

GetUriOptions​

PropTypeDescriptionSince
pathstringThe path of the file to get the URI for1.0.0
directory
Directory
The Directory to get the file under1.0.0

StatOptions​

PropTypeDescriptionSince
pathstringThe path of the file to get data about1.0.0
directory
Directory
The Directory to get the file under1.0.0

CopyOptions​

PropTypeDescriptionSince
fromstringThe existing file or directory1.0.0
tostringThe destination file or directory1.0.0
directory
Directory
The Directory containing the existing file or directory1.0.0
toDirectory
Directory
The Directory containing the destination file or directory. If not supplied will use the 'directory' parameter as the destination1.0.0

CopyResult​

PropTypeDescriptionSince
uristringThe uri where the file was copied into4.0.0

DownloadFileResult​

PropTypeDescriptionSince
pathstringThe path the file was downloaded to.5.1.0
blobBlobThe blob data of the downloaded file. This is only available on web.5.1.0

DownloadFileOptions​

PropTypeDescriptionDefaultSince
pathstringThe 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
progressbooleanAn 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
recursivebooleanWhether to create any missing parent directories.false5.1.2

PluginListenerHandle​

PropType
remove() => Promise<void>

ProgressStatus​

PropTypeDescriptionSince
urlstringThe url of the file being downloaded.5.1.0
bytesnumberThe number of bytes downloaded so far.5.1.0
contentLengthnumberThe total number of bytes to download for this file.5.1.0

Type Aliases​

PermissionState​

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

ReadFileInChunksCallback​

Callback for receiving chunks read from a file, or error if something went wrong.

(chunkRead: ReadFileResult | null, err?: any): void

CallbackID​

string

StatResult​

FileInfo

RenameOptions​

CopyOptions

ProgressListener​

A listener function that receives progress events.

(progress: ProgressStatus): void

Enums​

Directory​

MembersValueDescriptionSince
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 accessible 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 accessible 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 accessible on Android 11 or newer.1.0.0
ExternalCache'EXTERNAL_CACHE'The external cache directory. On iOS it will use the Documents directory. On Android it's the primary shared/external cache.7.1.0
LibraryNoCloud'LIBRARY_NO_CLOUD'The Library directory without cloud backup. Used in iOS. On Android it's the directory holding application files.7.1.0
Temporary'TEMPORARY'A temporary directory for iOS. On Android it's the directory holding the application cache.7.1.0

Encoding​

MembersValueDescriptionSince
UTF8'utf8'Eight-bit UCS Transformation Format1.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

Errors​

Since version 7.1.0, the plugin returns specific errors with specific codes on native Android and iOS. Web does not follow this standard for errors.

The following table list all the plugin errors:

Error codePlatform(s)Message
OS-PLUG-FILE-0004iOSCordova / Capacitor bridge isn’t initialized.
OS-PLUG-FILE-0005Android, iOSThe method input parameters aren’t valid.
OS-PLUG-FILE-0006Android, iOSInvalid path was provided.
OS-PLUG-FILE-0007AndroidUnable to perform file operation, user denied permission request.
OS-PLUG-FILE-0008Android, iOSOperation failed because file does not exist.
OS-PLUG-FILE-0009AndroidOperation not supported for provided input.
OS-PLUG-FILE-0010Android, iOSDirectory already exists, cannot be overwritten.
OS-PLUG-FILE-0011Android, iOSMissing parent directory – possibly recursive=false was passed or parent directory creation failed.
OS-PLUG-FILE-0012Android, iOSCannot delete directory with children; received recursive=false but directory has contents.
OS-PLUG-FILE-0013Android, iOSThe operation failed with an error.