Storage Adapters

Payload offers additional storage adapters to handle file uploads. These adapters allow you to store files in different locations, such as Amazon S3, Vercel Blob Storage, Google Cloud Storage, and more.

Service	Package
Vercel Blob	`@payloadcms/storage-vercel-blob`
AWS S3	`@payloadcms/storage-s3`
Azure	`@payloadcms/storage-azure`
Google Cloud Storage	`@payloadcms/storage-gcs`
R2	`@payloadcms/storage-r2`

Configuration

Storage adapters are registered under the top-level storage key in your Payload config. This placement ensures that upload hooks, static file handlers, and upload instructions are wired up before any plugin modifies the config.

1import { s3Storage } from '@payloadcms/storage-s3'
2import { buildConfig } from 'payload'
3
4export default buildConfig({
5  storage: [
6    s3Storage({
7      bucket: process.env.S3_BUCKET,
8      collections: { media: true },
9      config: { region: process.env.S3_REGION },
10    }),
11  ],
12  // ... rest of config
13})

Upload Instructions

By default, the Admin includes the file in the normal document create or update request. When an adapter's upload instructions provide a better browser upload flow, the Admin uses them instead:

1Admin
2  -> asks POST /api/upload-instructions how to upload this file
3
4Payload
5  -> checks access and file limits
6  -> returns the storage adapter's instructions
7
8Admin
9  -> follows the returned instructions
10  -> creates or updates the document with the completed upload metadata

With clientUploads enabled, S3, Azure, and GCS upload directly to storage instead of through Payload. Providers that need their own SDK return a named instruction handled by their Admin helper. R2 uses the same flow to split the file into smaller requests, even though Payload still handles each chunk.

The upload-instructions endpoint is also available for every upload collection. Other clients, including MCP, can use it when they cannot attach a file to the document request. Without direct provider instructions, Payload returns a temporary upload URL instead. Both paths still run normal validation, image processing, and hooks during document creation.

Vercel Blob Storage

@payloadcms/storage-vercel-blob

Installation

1pnpm add @payloadcms/storage-vercel-blob

Usage

Configure the collections object to specify which collections should use the Vercel Blob adapter. The slug must match one of your existing collection slugs.
Ensure you have BLOB_READ_WRITE_TOKEN set in your Vercel environment variables. This is usually set by Vercel automatically after adding blob storage to your project.
When enabled, this package will automatically set disableLocalStorage to true for each collection.
When deploying to Vercel, server uploads are limited to 4.5MB. Set clientUploads to true to use upload instructions and send files directly to Vercel Blob.

1import { vercelBlobStorage } from '@payloadcms/storage-vercel-blob'
2import { Media } from './collections/Media'
3import { MediaWithPrefix } from './collections/MediaWithPrefix'
4
5export default buildConfig({
collections: [Media, MediaWithPrefix],
storage: [
  vercelBlobStorage({
    enabled: true, // Optional, defaults to true
    // Specify which collections should use Vercel Blob
    collections: {
      media: true,
      'media-with-prefix': {
        prefix: 'my-prefix',
      },
    },
    // Token provided by Vercel once Blob storage is added to your Vercel project
    token: process.env.BLOB_READ_WRITE_TOKEN,
  }),
],
21})

Configuration Options

Option	Description	Default
`enabled`	Whether or not to enable the plugin	`true`
`collections`	Collections to apply the Vercel Blob adapter to
`addRandomSuffix`	Must be `false` or omitted; enabled adapters with configured collections reject `true`.	`false`
`cacheControlMaxAge`	Cache-Control max-age in seconds	`365 * 24 * 60 * 60` (1 Year)
`token`	Vercel Blob storage read/write token	`''`
`clientUploads`	Upload directly to Vercel Blob instead of through Payload.
`useCompositePrefixes`	Always combine collection prefix with document prefix, even when the document prefix already contains it.	`false`

Migrating Random Suffix Uploads

Remove addRandomSuffix: true or set it to false. Payload records exact storage paths for the current file, original, and stored variants, and uses those paths for reads, rollback, and deletion. Provider-assigned suffixes change these paths after upload and are incompatible with this lifecycle. New managed uploads already use distinct _objectKey folders to avoid overwriting retained objects.

An enabled Vercel Blob adapter with configured collections rejects this option during initialization, before any upload or copy. Explicitly disabled adapters and adapters disabled by a missing token retain their existing behavior. Changing the option does not rename existing blobs; if their actual paths differ from saved file metadata, migrate those paths and metadata together.

S3 Storage

@payloadcms/storage-s3

Installation

1pnpm add @payloadcms/storage-s3

Usage

Configure the collections object to specify which collections should use the S3 Storage adapter. The slug must match one of your existing collection slugs.
The config object can be any S3ClientConfig object (from @aws-sdk/client-s3). This is highly dependent on your AWS setup. Check the AWS documentation for more information.
When enabled, this package will automatically set disableLocalStorage to true for each collection.
When deploying to Vercel, server uploads are limited to 4.5MB. Set clientUploads to true to use upload instructions and send files directly to S3. You must allow CORS PUT requests and the If-None-Match request header from your website.
Configure signedDownloads (either globally or per-collection in collections) to use presigned URLs for files downloading. This can improve performance for large files (like videos) while still respecting your access control. Additionally, with signedDownloads.shouldUseSignedURL you can specify a condition whether Payload should use a presigned URL, if you want to use this feature only for specific files.
You can conditionally enable the plugin using the enabled option. For example, enabled: Boolean(process.env.S3_BUCKET) skips the plugin in local development when credentials are not set.

1import { s3Storage } from '@payloadcms/storage-s3'
2import { Media } from './collections/Media'
3import { MediaWithPrefix } from './collections/MediaWithPrefix'
4
5export default buildConfig({
collections: [Media, MediaWithPrefix],
storage: [
  s3Storage({
    collections: {
      media: true,
      'media-with-prefix': {
        prefix,
      },
      'media-with-presigned-downloads': {
        // Filter only mp4 files
        signedDownloads: {
          shouldUseSignedURL: ({ collection, filename, req }) => {
            return filename.endsWith('.mp4')
          },
        },
      },
    },
    bucket: process.env.S3_BUCKET,
    config: {
      credentials: {
        accessKeyId: process.env.S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
      },
      region: process.env.S3_REGION,
      // ... Other S3 configuration
    },
  }),
],
34})

Configuration Options

Option	Description	Default
`enabled`	Whether or not to enable the plugin	`true`
`collections`	Collections to apply the S3 adapter to
`bucket`	The name of the S3 bucket
`config`	`S3ClientConfig` object passed to the AWS SDK client
`acl`	Access control list for uploaded files (e.g. `'public-read'`)	`undefined`
`clientUploads`	Upload directly to S3 instead of through Payload.
`signedDownloads`	Use presigned URLs for file downloads. Can be overridden per collection
`useCompositePrefixes`	Always combine collection prefix with document prefix, even when the document prefix already contains it.	`false`

For full S3ClientConfig options, see the AWS SDK Package and S3ClientConfig docs.

Using with Cloudflare R2 (via S3 API)

Cloudflare R2 exposes an S3-compatible API, so you can use @payloadcms/storage-s3 to connect to it. This is the recommended approach when deploying to Vercel, Netlify, or any Node.js environment. (The @payloadcms/storage-r2 adapter is for Cloudflare Workers only, where R2 is available as a native bucket binding.)

1import { s3Storage } from '@payloadcms/storage-s3'
2
3export default buildConfig({
collections: [Media],
storage: [
  s3Storage({
    enabled: Boolean(process.env.R2_BUCKET),
    collections: {
      media: {
        disablePayloadAccessControl: true,
        generateFileURL: ({ filename, prefix }) => {
          const key = prefix ? `${prefix}/${filename}` : filename
          return `${process.env.R2_PUBLIC_URL}/${key}`
        },
      },
    },
    bucket: process.env.R2_BUCKET,
    config: {
      credentials: {
        accessKeyId: process.env.R2_ACCESS_KEY_ID,
        secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
      },
      region: 'auto',
      // R2 S3 API endpoint — for uploads only, not for serving files
      endpoint: process.env.R2_ENDPOINT,
      forcePathStyle: true,
    },
  }),
],
30})

Required environment variables:

1R2_BUCKET=my-bucket
2R2_ACCESS_KEY_ID=...
3R2_SECRET_ACCESS_KEY=...
4R2_ENDPOINT=https://<accountId>.r2.cloudflarestorage.com
5R2_PUBLIC_URL=https://media.yourdomain.com

region: 'auto' — required by R2; standard AWS region values are not accepted
endpoint — your R2 S3 API endpoint from the Cloudflare dashboard. This is for uploads only — not for serving files
forcePathStyle: true — required for R2's path-style bucket addressing
R2_PUBLIC_URL — your bucket's public URL (either the *.r2.dev subdomain or a custom domain you've connected in Cloudflare). This is separate from the S3 API endpoint
disablePayloadAccessControl: true — bypasses Payload's file proxy so URLs point directly to your public R2 domain

Azure Blob Storage

@payloadcms/storage-azure

Installation

1pnpm add @payloadcms/storage-azure

Usage

Configure the collections object to specify which collections should use the Azure Blob adapter. The slug must match one of your existing collection slugs.
When enabled, this package will automatically set disableLocalStorage to true for each collection.
When deploying to Vercel, server uploads are limited to 4.5MB. Set clientUploads to true to use upload instructions and send files directly to Azure.

clientUploads and CORS: Client uploads use the Azure Blob SDK, which splits large files into blocks (avoiding the ~5GB limit of a single upload request). Because the SDK sends x-ms-* headers, the browser issues a CORS preflight, so your storage account's CORS rules must allow the OPTIONS and PUT methods and the required headers. Configure a CORS rule on the Blob service (Storage account → Resource sharing (CORS)):

Field	Value
Allowed origins	Your site origin (e.g. `https://example.com`)
Allowed methods	`GET,PUT,OPTIONS` (`HEAD` if reading in-browser)
Allowed headers	`` (or at minimum `x-ms-,content-type,content-length`)
Exposed headers	`*`
Max age	`3600`

If you previously configured CORS for the older single-PUT upload flow, broaden Allowed headers to include the x-ms-* headers when upgrading.

Create-only client uploads require Azure Blob Storage service API version 2026-04-06 or newer. Ensure local emulators support that version.

1import { azureStorage } from '@payloadcms/storage-azure'
2import { Media } from './collections/Media'
3import { MediaWithPrefix } from './collections/MediaWithPrefix'
4
5export default buildConfig({
collections: [Media, MediaWithPrefix],
storage: [
  azureStorage({
    collections: {
      media: true,
      'media-with-prefix': {
        prefix,
      },
    },
    allowContainerCreate:
      process.env.AZURE_STORAGE_ALLOW_CONTAINER_CREATE === 'true',
    baseURL: process.env.AZURE_STORAGE_ACCOUNT_BASEURL,
    connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
    containerName: process.env.AZURE_STORAGE_CONTAINER_NAME,
  }),
],
22})

Configuration Options

Option	Description	Default
`enabled`	Whether or not to enable the plugin	`true`
`collections`	Collections to apply the Azure Blob adapter to
`allowContainerCreate`	Whether or not to allow the container to be created if it does not exist	`false`
`containerAccess`	Public access level for a container the plugin creates. `'private'` (default) serves blobs only through Payload's access-controlled route; `'blob'` / `'container'` expose them to anonymous clients directly from Azure. No effect on existing containers.	`'private'`
`baseURL`	Base URL for the Azure Blob storage account
`connectionString`	Azure Blob storage connection string
`containerName`	Azure Blob storage container name
`clientUploads`	Upload directly to Azure instead of through Payload.
`useCompositePrefixes`	Always combine collection prefix with document prefix, even when the document prefix already contains it.	`false`

Breaking change (private by default): When allowContainerCreate: true, the plugin now creates containers with private access, where it previously used public blob access. If you relied on files being served directly from the anonymous Azure blob URL (typically alongside disablePayloadAccessControl: true), set containerAccess: 'blob' to restore the old behaviour. Only newly created containers are affected — existing containers keep their current access level and must be updated manually if needed.

Google Cloud Storage

@payloadcms/storage-gcs

Installation

1pnpm add @payloadcms/storage-gcs

Usage

Configure the collections object to specify which collections should use the Google Cloud Storage adapter. The slug must match one of your existing collection slugs.
When enabled, this package will automatically set disableLocalStorage to true for each collection.
When deploying to Vercel, server uploads are limited to 4.5MB. Set clientUploads to true to use upload instructions and send files directly to GCS.
When using clientUploads, configure GCS CORS to allow PUT requests and include x-goog-if-generation-match in responseHeader. Existing client-upload CORS configurations must add this header when upgrading.

1import { gcsStorage } from '@payloadcms/storage-gcs'
2import { Media } from './collections/Media'
3import { MediaWithPrefix } from './collections/MediaWithPrefix'
4
5export default buildConfig({
collections: [Media, MediaWithPrefix],
storage: [
  gcsStorage({
    collections: {
      media: true,
      'media-with-prefix': {
        prefix,
      },
    },
    bucket: process.env.GCS_BUCKET,
    options: {
      apiEndpoint: process.env.GCS_ENDPOINT,
      projectId: process.env.GCS_PROJECT_ID,
    },
  }),
],
22})

Configuration Options

Option	Description	Default
`enabled`	Whether or not to enable the plugin	`true`
`collections`	Collections to apply the storage to
`bucket`	The name of the bucket to use
`options`	Google Cloud Storage client configuration. See Docs
`acl`	Access control list for files that are uploaded	`Private`
`clientUploads`	Upload directly to GCS instead of through Payload.
`useCompositePrefixes`	Always combine collection prefix with document prefix, even when the document prefix already contains it.	`false`

R2 Storage

@payloadcms/storage-r2

Use this adapter to store uploads in a Cloudflare R2 bucket via the Cloudflare Workers environment. If you're connecting to R2 from a Node.js environment (Vercel, Netlify, etc.) using the S3-compatible API, see Using with Cloudflare R2 (via S3 API) instead.

Installation

1pnpm add @payloadcms/storage-r2

Usage

Configure the collections object to specify which collections should use r2. The slug must match one of your existing collection slugs and be an upload type.
Pass in the R2 bucket binding to the bucket option, this should be done in the environment where Payload is running (e.g. Cloudflare Worker).
You can conditionally determine whether or not to enable the plugin with the enabled option.

1export default buildConfig({
collections: [Media],
storage: [
  r2Storage({
    collections: {
      media: true,
    },
    bucket: cloudflare.env.R2,
  }),
],
11})

Custom Storage Adapters

If you need to create a custom storage adapter, you can use the @payloadcms/plugin-cloud-storage package. This package is used internally by the storage adapters mentioned above.

Installation

pnpm add @payloadcms/plugin-cloud-storage

Usage

Reference any of the existing storage adapters for guidance on how this should be structured. Create an adapter following the GeneratedAdapter interface. Then, pass the adapter to the cloudStorage plugin.

1type FileOperationArgs = {
collection: SanitizedCollectionConfig
from: string
to: string
mimeType?: string
req: PayloadRequest
7}
8
9export interface GeneratedAdapter {
copyFile: (args: FileOperationArgs) => Promise<void>
deleteFile: (args: {
  collection: CollectionConfig
  req: PayloadRequest
  storageFilePath: string
}) => Promise<void> | void
/**
 * Additional fields to be injected into the base
 * collection and image sizes
 */
fields?: Field[]
/**
 * Generates the public URL for a file
 */
generateURL?: GenerateURL
handleDelete: HandleDelete
handleUpload: HandleUpload
name: string
onInit?: () => void
moveFile?: (args: FileOperationArgs) => Promise<void>
staticHandler: StaticHandler
uploadInstructions?: UploadInstructionsCapability
32}

from and to are complete storage keys, including prefixes. copyFile must leave the source in place, reject an occupied destination, and resolve only after the destination can be read. The optional moveFile method remains available to adapters, but core file rename always copies first and defers source deletion until the document update and its database transaction succeed. The key-based contract applies to path-addressed storage; an adapter using provider-assigned IDs needs a compatible mapping before it can support file versioning.

If a copy creates a destination and then fails its readability check or a post-copy permissions update, the adapter must remove that failed destination before rejecting. Cleanup must target only the object created by that attempt, using a returned generation, version ID, or ETag condition where supported. Never delete an occupied destination after a create-only operation rejects. If cleanup also fails, preserve the original copy error and log the exact remaining storage path for manual cleanup. The first-party adapters follow this contract, including incomplete S3 multipart uploads and Vercel Blob's streamed fallback.

Custom adapters must implement deleteFile for upload rollback and cleanup of unreferenced objects. Its storageFilePath is the complete object path, including prefixes and _objectKey; delete that exact object without requiring a saved document. Failed uploads may need cleanup before a document exists, and version pruning may remove the last document reference before cleanup runs. The plugin rejects enabled adapters without deleteFile during configuration.

handleDelete retains its document-based contract: when it is used for legacy document deletion, it receives the saved file document along with the filename and resolved storage path. An adapter that only needs the storage path can share its deletion implementation between deleteFile and handleDelete, as the first-party adapters do.

An explicit file rename copies stored objects to new current keys and keeps the source readable while the database operation is pending. After the document update and its database transaction succeed, Payload removes only source objects with no remaining document or version references. A failed rename preserves the sources and removes staged copies that no persisted document or version references. This applies with or without versions and regardless of whether the adapter supplies moveFile. A process crash before cleanup may leave extra objects, but committed source references remain readable.

The first-party S3 adapter uses single or multipart server-side copy. The R2 Workers binding supports ordinary uploads and reads without S3 credentials, but copy-dependent file versioning operations require copyCredentials with an R2 account ID, bucket, S3 access key ID, and secret. Azure copies through authenticated source and destination streams, so private sources work but copy traffic passes through the Payload server. GCS uses its provider copy API; Vercel Blob uses its provider copy API with exact destination pathnames. Grant each adapter read and write access to the source and destination, plus object metadata and tag access where used. S3 multipart copy also needs permission to abort incomplete multipart uploads, and copy cleanup needs permission to delete objects (including specific object versions when S3 bucket versioning is enabled); KMS-encrypted S3 objects need the corresponding decrypt and encrypt permissions.

Payload removes versioned upload objects only after their last document or saved version reference is gone and the database operation has committed. If an object deletion fails, Payload logs the complete storage key and leaves the object in place. Before retrying manually, check the current file, original, and stored variants in every current document and retained version. Each representation's filename, prefix, and _objectKey identify its location through the configured adapter's path resolver. Remove the failed object through the storage provider only when none of these locations resolves to its exact key. Failed deletions are not retried automatically.

When providing upload instructions, set uploadInstructions.useInAdmin to true when the Admin panel should use them instead of attaching the whole file to the document request. This is useful for direct-to-storage uploads and for flows such as chunked uploads that still pass through Payload.

staticHandler receives params.operation: 'read' for an ordinary file request (treat a missing value as 'read', for backward compatibility), or 'transform' when Payload is reading the file's bytes on behalf of a file transformer, which only happens when at least one transformer is configured. For 'transform', return the full object body rather than a redirect to a signed/public URL, and skip Range handling, conditional/ETag short-circuiting, and modifyResponseHeaders — Payload applies headers once, on the final response, after every transformer has run. The five first-party adapters already implement this; a custom adapter only needs to branch on operation if it currently redirects to an external URL for 'read'.

1import { buildConfig } from 'payload'
2import { cloudStoragePlugin } from '@payloadcms/plugin-cloud-storage'
3
4export default buildConfig({
plugins: [
  // cloudStoragePlugin is a low-level building block — place it in plugins, not storage.
  // The built-in adapter packages (s3Storage, gcsStorage, etc.) wrap this internally
  // and are used via storage instead.
  cloudStoragePlugin({
    collections: {
      'my-collection-slug': {
        adapter: theAdapterToUse, // see docs for the adapter you want to use
      },
    },
  }),
],
// The rest of your config goes here
18})

Plugin options

This plugin is configurable to work across many different Payload collections. A * denotes that the property is required.

Option	Type	Description
`collections` *	`Record<string, CollectionOptions>`	Object with keys set to the slug of collections you want to enable the plugin for, and values set to collection-specific options.
`enabled`	`boolean`	To conditionally enable/disable plugin. Default: `true`.

Collection-specific options

Option	Type	Description
`adapter` *	Adapter	Pass in the adapter that you'd like to use for this collection. You can also set this field to `null` for local development if you'd like to bypass cloud storage in certain scenarios and use local storage.
`disableLocalStorage`	`boolean`	Choose to disable local storage on this collection. Defaults to `true`.
`disablePayloadAccessControl`	`true`	Set to `true` to disable Payload's Access Control. More
`generateFileURL`	GenerateFileURL	Override the generated file URL with one that you create.
`prefix`	`string`	Set to `media/images` to upload files inside `media/images` folder in the bucket.

Prefix Composition

Storage adapters support two types of prefixes:

Collection prefix: Set at the adapter configuration level (e.g., prefix: 'media-folder')
Document prefix: Set per-document via the prefix field on the upload collection

New uploads are always written within the configured collection prefix. By default, a document prefix that is already within the collection prefix is used as-is. Any other document prefix is nested beneath the collection prefix.

With useCompositePrefixes: true, the collection and document prefixes are always combined. This differs when the document prefix already contains the collection prefix:

1# Without useCompositePrefixes (default)
2Collection prefix: uploads
3Document prefix: uploads/user-123
4Result: uploads/user-123/image.jpg
5
6# With useCompositePrefixes: true
7Collection prefix: uploads
8Document prefix: uploads/user-123
9Result: uploads/uploads/user-123/image.jpg

Persisted paths remain backward compatible. Existing files keep their stored prefixes for reads, generated URLs, replacement cleanup, and deletion, even when those paths are outside the configured collection prefix. Replacing an existing file writes the replacement within the collection prefix and cleans up the previous stored location.

Upgrading does not move existing objects. If another system relies on historical object paths, plan a separate migration before changing or replacing those files. New uploads and replacements may persist a normalized prefix that differs from legacy metadata.

Custom adapters using getFilePrefix from @payloadcms/plugin-cloud-storage/utilities should forward the static handler's access-checked doc to the helper. Its prefixQueryParam option is deprecated and ignored, but remains accepted for TypeScript compatibility. Without a document, the helper uses the upload reference or looks up the stored prefix by filename. Direct callers must perform their own access checks before supplying a document.

1storage: [
s3Storage({
  collections: {
    media: {
      prefix: 'uploads', // All files go under uploads/
    },
  },
  useCompositePrefixes: true, // Document prefixes append to collection prefix
  bucket: process.env.S3_BUCKET,
  // ...
}),
12],

Payload Access Control

Payload ships with Access Control that runs even on statically served files. The same read Access Control property on your upload-enabled collections is used, and it allows you to restrict who can request your uploaded files.

To preserve this feature, by default, this plugin keeps all file URLs exactly the same. Your file URLs won't be updated to point directly to your cloud storage source, as in that case, Payload's Access control will be completely bypassed and you would need public readability on your cloud-hosted files.

Instead, all uploads will still be reached from the default /collectionSlug/staticURL/filename path. This plugin will "pass through" all files that are hosted on your third-party cloud service—with the added benefit of keeping your existing Access Control in place.

If this does not apply to you (your upload collection has read: () => true or similar) you can disable this functionality by setting disablePayloadAccessControl to true. When this setting is in place, this plugin will update your file URLs to point directly to your cloud host. For a concrete example, see Using with Cloudflare R2 (via S3 API).

Conditionally Enabling/Disabling

The proper way to conditionally enable/disable this plugin is to use the enabled property.

1cloudStoragePlugin({
enabled: process.env.MY_CONDITION === 'true',
collections: {
  'my-collection-slug': {
    adapter: theAdapterToUse, // see docs for the adapter you want to use
  },
},
8}),

Was this page helpful?

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Storage Adapters

Configuration

Upload Instructions

Vercel Blob Storage

Installation

Usage

Configuration Options

Migrating Random Suffix Uploads

S3 Storage

Installation

Usage

Configuration Options

Using with Cloudflare R2 (via S3 API)

Azure Blob Storage

Installation

Usage

Configuration Options

Google Cloud Storage

Installation

Usage

Configuration Options

R2 Storage

Installation

Usage

Custom Storage Adapters

Installation

Usage

Plugin options

Collection-specific options

Prefix Composition

Payload Access Control

Conditionally Enabling/Disabling

File Transformers