Skip to content

filestore

Production-ready file upload toolkit for FastAPI

PyPI version Python versions Package status CI Docs License Ruff Typed

filestore is a small FastAPI upload library with a simple dependency-based API and production-grade defaults. It keeps the happy path short, but adds the things real services usually need.

Features

  • Multiple Storage Backends

    Local filesystem, in-memory, Amazon S3, Google Cloud Storage, and Azure Blob Storage — all with the same API.

  • Built-in Validation

    Validate file size, extension, and content type out of the box. Add custom filter callbacks for application-specific rules.

  • Sync & Async Callbacks

    Dynamically resolve filenames, destinations, filters, and metadata with sync or async callables.

  • Multi-Field Support

    Handle multiple upload fields in a single request with per-field configuration and validation.

  • FastAPI Native

    Works as a standard FastAPI dependency — just Depends() and go. No middleware, no magic.

  • Lean Install

    Zero cloud SDK dependencies by default. Install only the extras you need: filestore[s3], filestore[gcp], filestore[azure].

Quick Example

from fastapi import Depends, FastAPI
from filestore import LocalStorage, Store

app = FastAPI()

storage = LocalStorage(
    name="file",
    required=True,
    config={"destination": "uploads", "base_url": "/media"},
)


@app.post("/upload")
async def upload(store: Store = Depends(storage)):
    file_data = store.first("file")
    return {
        "status": store.status,
        "filename": file_data.filename,
        "url": file_data.url,
    }

That's it. Uploads are validated, written atomically to disk, and collision-free by default.

Next Steps