---
title: Installation
description: Install files-sdk and the optional peer dependencies for the adapter you're using - anything you don't import is never bundled. ESM only, Node 22+ and Bun.
---

`files-sdk` itself is small - a handful of lightweight runtime dependencies (`aws4fetch`, `commander`, `fflate`, `mime`, `p-map`, `picomatch`, and `safe-regex2`, plus an optional `@modelcontextprotocol/sdk` for the MCP server) behind a tree of subpath exports. Install the package, then add the peer dependencies for the adapter you're wiring up. Anything you don't import is never bundled.

```package-install
npm install files-sdk
```

Upgrading from v2? See [Migrating to v3](/docs/migrating-to-v3) for what changed.

The package ships its own TypeScript types, so there's no `@types/files-sdk` to chase down. It's published as ESM only (`"type": "module"`) and targets modern runtimes - Node 22+ and Bun. From a CommonJS file, reach it with a dynamic `import()`.

## Adapter peer dependencies

Adapters are subpath exports - `files-sdk/s3`, `files-sdk/r2`, `files-sdk/vercel-blob`, and so on - and each one's provider SDK is an optional peer dependency, loaded only when you import that adapter's subpath. The SDK you don't import is never bundled, so both install size and cold-start cost stay proportional to the providers you actually wire up.

Install the peer deps for your adapter alongside the SDK. For R2 over HTTP - and for S3 and every other S3-compatible store, since MinIO, Backblaze, Wasabi, DigitalOcean Spaces, and the rest all wrap the same client:

```package-install
files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner
```

Add `@aws-sdk/lib-storage` as well if you use `multipart` or `onProgress`, or upload a `ReadableStream` of unknown length, on an S3-family adapter using the AWS SDK client. Without it, those uploads throw a `FilesError` that names the missing package. R2 can skip the `@aws-sdk/*` packages entirely: its Workers binding and its `client: "fetch"` engine (the default inside Cloudflare Workers) need none of them.

The shape is the same for every adapter, only the packages change: Google Cloud Storage adds `@google-cloud/storage`; Azure adds `@azure/storage-blob` (plus `@azure/identity` only if you build a `credential` with it); Vercel Blob needs only `@vercel/blob`. A few adapters need no extra packages at all - `files-sdk/fs`, `files-sdk/memory`, and `files-sdk/bun-s3` use primitives the runtime already provides, and `files-sdk/s3-fetch` signs requests with the bundled `aws4fetch`.

The [per-adapter docs](/docs/adapters/s3) list the exact packages for each provider, and the [provider catalog](/docs/providers) exposes the same data programmatically (`peerDeps`) if you're generating install commands or building a config UI.

## Missing a peer dependency?

Import an adapter without its peer installed and Node throws `ERR_MODULE_NOT_FOUND` naming the package that's missing - the SDK doesn't vendor or shim provider clients, so the failure is loud and specific rather than a silent fallback. Install the named package and the import resolves. R2, MinIO, and RustFS are the exception: they load the AWS SDK lazily (so a `client: "fetch"` bundle never pulls it in), so the missing-module error arrives on the first call instead, as the `cause` of a `FilesError`.

Once your adapter's packages are in place, head to [Usage](/docs/usage) to construct a `Files` instance and run the core methods.