Folders_
Organize files in Appwrite Storage buckets with virtual folders. Learn how to upload files into folders, list files by folder, and browse folders.
3 min read
Appwrite Storage lets you organize the files inside a bucket using virtual folders. Folders work like key prefixes in S3-compatible storage services: they are derived from the paths of your files, so you never create or delete folders explicitly.
How folders work
A bucket doesn't store folders as records. Instead, every file has a folder attribute, a path like photos/2026/, and folders are derived from these paths: a folder exists whenever at least one file's folder path places the file inside it. For example, uploading a single file with the folder photos/2026 is what brings both the photos/ and photos/2026/ folders into existence.
A file's folder is set once, when the file is uploaded, and defaults to the bucket root (an empty string). Folder paths are stored in a canonical form that always ends with a trailing slash, like photos/2026/. Each file also exposes a computed key attribute, which is the file's full virtual path: the folder followed by the file name, like photos/2026/Pink.png.
Because folders are derived from files, they exist implicitly. A folder appears as soon as the first file is uploaded into it and disappears when the last file inside it is deleted. There are no empty folders, no folder permissions, and no folder metadata to manage.
Unlike in S3, uploading a file with the same name to the same folder does not overwrite the existing file. Files are identified by their file ID, so multiple files can share the same key.
Upload files to a folder
To place a file inside a folder, pass the optional folder parameter when uploading the file. Nest folders using /, for example photos/2026. The trailing slash is optional on input and is added automatically when stored.
Folder paths are /-separated segments. A folder path must not start with /, must not contain empty, ., or .. segments or control characters, and can be at most 2,048 characters long including the trailing slash.
A file's folder can't be changed after upload. To move a file into a different folder, create the file again with the new folder and delete the original.
List files in a folder
Filter files by folder using queries on the folder attribute when listing files.
| Goal | Query |
|---|---|
Files directly inside photos/2026/ | Query.equal('folder', ['photos/2026/']) |
| Files at the bucket root only | Query.equal('folder', ['']) |
Files anywhere under photos/, including nested folders | Query.startsWith('folder', 'photos/') |
Query values must match the stored form of the folder path, which always includes the trailing slash. For example, Query.equal('folder', ['photos/2026/']) matches files in photos/2026/, but Query.equal('folder', ['photos/2026']) matches nothing.
List folders
Folders are aggregated from the files inside a bucket. To browse them, paginate through the bucket's files and collect the unique folder paths from each file's folder attribute, including the implied parent folders.
For example, a file with the folder photos/2026/july/ produces three folders:
photos/photos/2026/photos/2026/july/Scanning every file works well for small buckets. For buckets with many files, maintain your own folder index instead, for example in a Databases table that you update whenever you upload or delete files.
Permissions
Folders don't carry their own permissions. Access is derived from the files inside them. When a bucket uses file security, listing files returns only the files a user can read, so aggregating folders discovers only the folders that contain at least one such file.
Was this page helpful?
Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.