Documents Directory: What It Is, Purpose and File Access

What is Documents Directory in iOS?

Documents Directory is a directory inside the iOS app sandbox designed for storing user data that should persist between launches and be accessible to the user. Each app gets its own isolated sandbox, and Documents is one of the key directories alongside Caches, tmp and Library.

iOS uses a strict sandbox: an app does not have access to the file system of other apps or to system directories without special permissions. Documents Directory is the only directory whose contents the user can view via iTunes File Sharing (when the corresponding UIFileSharingEnabled key is enabled in Info.plist).

According to Apple WWDC 2023, more than 85% of apps in the App Store use Documents Directory to store at least one type of user data — from exported PDFs to saved game files and exported images.

It is important for the developer to understand: files in Documents are automatically included in iCloud and iTunes backups. If an app stores large amounts of recoverable data in Documents (e.g., image cache or temporary files), this leads to unnecessary consumption of the user's iCloud storage space.

How to Get the Path to Documents Directory

In Swift, the path to Documents Directory is obtained through FileManager. Apple recommends using URL-based API instead of string-based for better compatibility with modern iOS capabilities.

import Foundation

let fileManager = FileManager.default
guard let documentsURL = fileManager.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first else { return }

// Create file in Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C uses NSSearchPathForDirectoriesInDomains — an older but still supported approach that returns a string path instead of a URL.

@import Foundation;

NSArray *paths = NSSearchPathForDirectoriesInDomains(
    NSDocumentDirectory,
    NSUserDomainMask,
    YES
);
NSString *documentsPath = paths.firstObject;
NSString *filePath = [documentsPath stringByAppendingPathComponent:@"report.pdf"];

Modern projects in Swift should use FileManager.urls, since this method returns a URL rather than a string, which reduces the risk of path encoding errors and makes the code more type-safe.

What Data to Store in Documents

Documents Directory is intended for data created by the user or explicitly needed by the user. Apple highlights several categories that are appropriate for this directory.

User Documents and Files

Files that the user creates or imports — text documents, PDFs, images, exported reports, backup files. This data has direct value to the user, and its loss would be critical.

Game Saves and App State

Game saves, app state files, exported projects — everything the user expects to restore after reinstalling the app. However, for critical data it is recommended to additionally use iCloud Key-Value Storage or Core Data with iCloud sync.

The key criterion: if data can be re-downloaded from the network or recreated — it belongs in Caches, not in Documents. Every gigabyte in Documents is a gigabyte in the user's iCloud backup.

Backup and Synchronization

iOS automatically includes the contents of Documents Directory in backups when the device is connected to iTunes or when syncing with iCloud. This behavior cannot be disabled at the directory level — only per-file via the NSURLIsExcludedFromBackupKey attribute.

Starting with iOS 5.0, Apple began rejecting apps that store large amounts of recoverable data in Documents. Apple's recommendation: files that can be re-downloaded should be stored in Caches Directory with the backup exclusion flag.

import Foundation

let documentsURL = FileManager.default
    .urls(for: .documentDirectory, in: .userDomainMask)
    .first!

// Exclude file from iCloud backup
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

var fileURL = documentsURL.appendingPathComponent("cached_data.json")
try fileURL.setResourceValues(resourceValues)

iCloud synchronization works via NSUbiquitousContainer if the app uses iCloud Documents. In this case, files from Documents Directory are automatically synced across the user's devices. For apps without iCloud, synchronization is limited to backup.

Documents Directory vs Caches Directory

The difference between Documents and Caches is one of the most common misconceptions among beginner iOS developers. The main difference: the system can delete files from Caches at any time to free up space, but it never touches Documents without user knowledge.

According to Apple Developer Documentation (2024), improper use of Documents Directory is one of the common reasons for app rejection during review: if an app stores more than a few megabytes of recoverable data in Documents, Apple recommends moving it to Caches or applying NSURLIsExcludedFromBackupKey.

A practical rule: if the user would be upset about losing the file — store it in Documents. If the file can be re-downloaded or regenerated — store it in Caches.

Best Practices for Working with Documents

Experienced iOS developers have developed several rules that help avoid problems with Documents Directory at all stages of the app lifecycle — from development to App Store publication.

Monitoring Directory Size

Regularly check the size of Documents Directory via FileManager.enumerator(at:includingPropertiesForKeys:). If the size exceeds 100 MB for non-user data — it is a reason to reconsider the storage architecture.

Excluding Recoverable Files from Backup

For any files that can be re-downloaded, set isExcludedFromBackup = true. This reduces the load on the user's iCloud storage and decreases the risk of App Review rejection.

Migration During Updates

When changing the data format in Documents, plan for migration: do not delete old files until you are sure new ones are correctly created. Use version-specific subdirectories.

import Foundation

let documentsURL = FileManager.default
    .urls(for: .documentDirectory, in: .userDomainMask)
    .first!

let versionDir = documentsURL.appendingPathComponent("v2")
try FileManager.default.createDirectory(
    at: versionDir,
    withIntermediateDirectories: true
)

Following these practices reduces the risk of user data loss, decreases iCloud backup size, and simplifies App Store review.