> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Storage Integrations

> Configure S3, Google Cloud Storage, and Azure Blob Storage

## Overview

Open WebUI supports cloud storage backends for scalable file storage. Choose between local filesystem, Amazon S3, Google Cloud Storage, or Azure Blob Storage based on your deployment needs.

## Storage Options

<CardGroup cols={2}>
  <Card title="Local Storage" icon="hard-drive">
    Default filesystem storage
  </Card>

  <Card title="Amazon S3" icon="aws">
    S3 and S3-compatible storage
  </Card>

  <Card title="Google Cloud Storage" icon="google">
    GCS buckets
  </Card>

  <Card title="Azure Blob Storage" icon="microsoft">
    Azure Storage containers
  </Card>
</CardGroup>

## Local Storage (Default)

Files are stored in the local filesystem.

### Configuration

```bash theme={null}
# Default - no configuration needed
STORAGE_PROVIDER=local
DATA_DIR=/app/backend/data
```

### Directory Structure

```
data/
├── uploads/           # User-uploaded files
├── cache/             # Temporary cache
└── ...
```

### Use Cases

<Check>Single-server deployments</Check>
<Check>Development environments</Check>
<Check>Small-scale production</Check>

<Warning>
  Local storage is not recommended for:

  * Multi-node deployments
  * High-availability setups
  * Large file volumes
</Warning>

## Amazon S3

Scalable object storage compatible with S3 API.

### Installation

```bash theme={null}
# Already included in requirements.txt
boto3==1.42.44
```

*File: backend/requirements.txt:120*

### Configuration

<CodeGroup>
  ```bash Environment Variables theme={null}
  STORAGE_PROVIDER=s3

  # AWS Credentials
  S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
  S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

  # S3 Configuration
  S3_BUCKET_NAME=open-webui-storage
  S3_REGION_NAME=us-east-1
  S3_ENDPOINT_URL=  # Optional, for S3-compatible services
  S3_KEY_PREFIX=uploads/  # Optional prefix for all keys

  # Advanced Options
  S3_USE_ACCELERATE_ENDPOINT=false
  S3_ADDRESSING_STYLE=auto  # auto, path, or virtual
  S3_ENABLE_TAGGING=false
  ```

  ```bash Docker theme={null}
  docker run -d -p 3000:8080 \
    -e STORAGE_PROVIDER=s3 \
    -e S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE \
    -e S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
    -e S3_BUCKET_NAME=open-webui-storage \
    -e S3_REGION_NAME=us-east-1 \
    -v open-webui:/app/backend/data \
    ghcr.io/open-webui/open-webui:main
  ```

  ```yaml Kubernetes theme={null}
  apiVersion: v1
  kind: Secret
  metadata:
    name: s3-credentials
  stringData:
    accessKeyId: AKIAIOSFODNN7EXAMPLE
    secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
  ---
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: storage-config
  data:
    STORAGE_PROVIDER: "s3"
    S3_BUCKET_NAME: "open-webui-storage"
    S3_REGION_NAME: "us-east-1"
  ```
</CodeGroup>

*File: backend/open\_webui/config.py:953*

### S3-Compatible Services

<Tabs>
  <Tab title="MinIO">
    ```bash theme={null}
    STORAGE_PROVIDER=s3
    S3_ENDPOINT_URL=http://minio:9000
    S3_ACCESS_KEY_ID=minioadmin
    S3_SECRET_ACCESS_KEY=minioadmin
    S3_BUCKET_NAME=open-webui
    S3_ADDRESSING_STYLE=path
    ```
  </Tab>

  <Tab title="Backblaze B2">
    ```bash theme={null}
    STORAGE_PROVIDER=s3
    S3_ENDPOINT_URL=https://s3.us-west-002.backblazeb2.com
    S3_ACCESS_KEY_ID=your-key-id
    S3_SECRET_ACCESS_KEY=your-app-key
    S3_BUCKET_NAME=your-bucket
    S3_REGION_NAME=us-west-002
    ```
  </Tab>

  <Tab title="DigitalOcean Spaces">
    ```bash theme={null}
    STORAGE_PROVIDER=s3
    S3_ENDPOINT_URL=https://nyc3.digitaloceanspaces.com
    S3_ACCESS_KEY_ID=your-access-key
    S3_SECRET_ACCESS_KEY=your-secret-key
    S3_BUCKET_NAME=your-space-name
    S3_REGION_NAME=nyc3
    ```
  </Tab>

  <Tab title="Wasabi">
    ```bash theme={null}
    STORAGE_PROVIDER=s3
    S3_ENDPOINT_URL=https://s3.wasabisys.com
    S3_ACCESS_KEY_ID=your-access-key
    S3_SECRET_ACCESS_KEY=your-secret-key
    S3_BUCKET_NAME=your-bucket
    S3_REGION_NAME=us-east-1
    ```
  </Tab>
</Tabs>

### IAM Policy

Minimum required permissions:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::open-webui-storage",
        "arn:aws:s3:::open-webui-storage/*"
      ]
    }
  ]
}
```

With tagging enabled:

```json theme={null}
{
  "Effect": "Allow",
  "Action": [
    "s3:GetObject",
    "s3:PutObject",
    "s3:DeleteObject",
    "s3:ListBucket",
    "s3:PutObjectTagging",
    "s3:GetObjectTagging"
  ],
  "Resource": [
    "arn:aws:s3:::open-webui-storage",
    "arn:aws:s3:::open-webui-storage/*"
  ]
}
```

### Advanced Features

<Accordion title="Transfer Acceleration">
  ```bash theme={null}
  S3_USE_ACCELERATE_ENDPOINT=true
  ```

  Requires S3 Transfer Acceleration to be enabled on the bucket.

  *File: backend/open\_webui/config.py:961*
</Accordion>

<Accordion title="Object Tagging">
  ```bash theme={null}
  S3_ENABLE_TAGGING=true
  ```

  Automatically tags objects with metadata for organization.

  *File: backend/open\_webui/config.py:965*
</Accordion>

<Accordion title="Custom Key Prefix">
  ```bash theme={null}
  S3_KEY_PREFIX=production/uploads/
  ```

  Adds a prefix to all object keys for organization.

  *File: backend/open\_webui/config.py:959*
</Accordion>

## Google Cloud Storage

Scalable object storage on Google Cloud Platform.

### Installation

```bash theme={null}
# Already included in requirements.txt
google-cloud-storage==3.9.0
```

*File: backend/requirements.txt:112*

### Configuration

<CodeGroup>
  ```bash Environment Variables theme={null}
  STORAGE_PROVIDER=gcs
  GCS_BUCKET_NAME=open-webui-storage

  # Authentication via JSON credentials
  GOOGLE_APPLICATION_CREDENTIALS_JSON='{"type":"service_account",...}'
  ```

  ```bash Service Account File theme={null}
  STORAGE_PROVIDER=gcs
  GCS_BUCKET_NAME=open-webui-storage
  GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
  ```

  ```bash Docker theme={null}
  docker run -d -p 3000:8080 \
    -e STORAGE_PROVIDER=gcs \
    -e GCS_BUCKET_NAME=open-webui-storage \
    -e GOOGLE_APPLICATION_CREDENTIALS_JSON='$(cat service-account.json)' \
    -v open-webui:/app/backend/data \
    ghcr.io/open-webui/open-webui:main
  ```
</CodeGroup>

*File: backend/open\_webui/config.py:967*

### Service Account Setup

<Steps>
  <Step title="Create Service Account">
    In Google Cloud Console:

    1. Navigate to IAM & Admin > Service Accounts
    2. Create a new service account
    3. Grant "Storage Object Admin" role
  </Step>

  <Step title="Generate Key">
    1. Click on the service account
    2. Go to Keys tab
    3. Add Key > Create new key
    4. Choose JSON format
  </Step>

  <Step title="Configure Open WebUI">
    Use the JSON key content in `GOOGLE_APPLICATION_CREDENTIALS_JSON`
  </Step>
</Steps>

### Required IAM Roles

* `roles/storage.objectAdmin` (or custom role with these permissions):
  * `storage.objects.create`
  * `storage.objects.delete`
  * `storage.objects.get`
  * `storage.objects.list`

### Bucket Configuration

Recommended bucket settings:

```bash theme={null}
# Create bucket
gsutil mb -l us-central1 gs://open-webui-storage

# Set uniform bucket-level access
gsutil uniformbucketlevelaccess set on gs://open-webui-storage

# Optional: Enable versioning
gsutil versioning set on gs://open-webui-storage
```

## Azure Blob Storage

Microsoft Azure's object storage solution.

### Installation

```bash theme={null}
# Already included in requirements.txt
azure-storage-blob==12.28.0
azure-identity==1.25.1
```

*File: backend/requirements.txt:103*

### Configuration

<CodeGroup>
  ```bash Environment Variables theme={null}
  STORAGE_PROVIDER=azure

  # Azure Storage Account
  AZURE_STORAGE_ENDPOINT=https://mystorageaccount.blob.core.windows.net
  AZURE_STORAGE_CONTAINER_NAME=open-webui
  AZURE_STORAGE_KEY=your-storage-account-key
  ```

  ```bash Connection String theme={null}
  STORAGE_PROVIDER=azure
  AZURE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=mystorageaccount;AccountKey=your-key;EndpointSuffix=core.windows.net"
  AZURE_STORAGE_CONTAINER_NAME=open-webui
  ```

  ```bash Managed Identity (Azure VM/AKS) theme={null}
  STORAGE_PROVIDER=azure
  AZURE_STORAGE_ENDPOINT=https://mystorageaccount.blob.core.windows.net
  AZURE_STORAGE_CONTAINER_NAME=open-webui
  # No key needed - uses managed identity
  ```
</CodeGroup>

*File: backend/open\_webui/config.py:972*

### Authentication Methods

<Tabs>
  <Tab title="Storage Account Key">
    ```bash theme={null}
    AZURE_STORAGE_KEY=your-64-char-key==
    ```

    Find in Azure Portal > Storage Account > Access Keys
  </Tab>

  <Tab title="Managed Identity">
    ```bash theme={null}
    # No key required
    # Assign "Storage Blob Data Contributor" role to managed identity
    ```

    Best for Azure VM, AKS, or App Service deployments
  </Tab>

  <Tab title="SAS Token">
    ```bash theme={null}
    AZURE_STORAGE_SAS_TOKEN=?sv=2021-06-08&ss=b&srt=sco...
    ```

    Generate in Azure Portal > Storage Account > Shared access signature
  </Tab>
</Tabs>

### Container Setup

<Steps>
  <Step title="Create Storage Account">
    ```bash theme={null}
    az storage account create \
      --name openwebuistorage \
      --resource-group open-webui-rg \
      --location eastus \
      --sku Standard_LRS
    ```
  </Step>

  <Step title="Create Container">
    ```bash theme={null}
    az storage container create \
      --name open-webui \
      --account-name openwebuistorage
    ```
  </Step>

  <Step title="Configure Access">
    For managed identity:

    ```bash theme={null}
    az role assignment create \
      --role "Storage Blob Data Contributor" \
      --assignee <managed-identity-id> \
      --scope /subscriptions/<sub-id>/resourceGroups/open-webui-rg/providers/Microsoft.Storage/storageAccounts/openwebuistorage
    ```
  </Step>
</Steps>

## Migration Between Storage Providers

<Warning>
  Migrating storage providers requires manual file transfer.
  Plan for downtime during migration.
</Warning>

### Migration Steps

<Steps>
  <Step title="Backup Current Storage">
    ```bash theme={null}
    # For local storage
    tar -czf backup.tar.gz /app/backend/data/uploads

    # For S3
    aws s3 sync s3://old-bucket ./backup/
    ```
  </Step>

  <Step title="Setup New Storage">
    Configure the new storage provider (create bucket/container, set permissions)
  </Step>

  <Step title="Transfer Files">
    <CodeGroup>
      ```bash Local to S3 theme={null}
      aws s3 sync /app/backend/data/uploads s3://new-bucket/uploads/
      ```

      ```bash S3 to GCS theme={null}
      gsutil -m rsync -r s3://old-bucket gs://new-bucket
      ```

      ```bash S3 to Azure theme={null}
      azcopy sync "https://s3.amazonaws.com/old-bucket" \
        "https://mystorageaccount.blob.core.windows.net/container"
      ```
    </CodeGroup>
  </Step>

  <Step title="Update Configuration">
    ```bash theme={null}
    # Update environment variables
    STORAGE_PROVIDER=s3  # or gcs, azure
    # Add provider-specific configuration
    ```
  </Step>

  <Step title="Restart and Verify">
    ```bash theme={null}
    docker restart open-webui

    # Test file upload and retrieval
    ```
  </Step>
</Steps>

## Cost Optimization

<CardGroup cols={2}>
  <Card title="Lifecycle Policies" icon="calendar">
    Configure automatic archival or deletion of old files
  </Card>

  <Card title="Storage Classes" icon="layer-group">
    Use infrequent access tiers for rarely accessed files
  </Card>

  <Card title="Compression" icon="file-zipper">
    Enable compression for text files before upload
  </Card>

  <Card title="Deduplication" icon="copy">
    Implement file hashing to avoid duplicate uploads
  </Card>
</CardGroup>

### S3 Lifecycle Example

```xml theme={null}
<LifecycleConfiguration>
  <Rule>
    <ID>MoveToIA</ID>
    <Status>Enabled</Status>
    <Transition>
      <Days>90</Days>
      <StorageClass>STANDARD_IA</StorageClass>
    </Transition>
  </Rule>
</LifecycleConfiguration>
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Access Denied Errors">
    **S3**:

    * Verify IAM policy permissions
    * Check bucket policy
    * Ensure credentials are correct

    **GCS**:

    * Verify service account has Storage Object Admin role
    * Check JSON credentials format
    * Ensure bucket exists and is accessible

    **Azure**:

    * Verify storage account key or SAS token
    * Check container exists
    * Verify managed identity role assignment
  </Accordion>

  <Accordion title="Connection Timeout">
    * Check network connectivity
    * Verify endpoint URL is correct
    * Check firewall rules
    * For S3: Verify region is correct
  </Accordion>

  <Accordion title="Upload Failures">
    * Check file size limits
    * Verify sufficient permissions
    * Check storage quota
    * Review application logs
  </Accordion>
</AccordionGroup>

## Best Practices

1. **Security**:
   * Use IAM roles instead of access keys when possible
   * Enable bucket/container encryption
   * Restrict public access
   * Rotate credentials regularly

2. **Performance**:
   * Choose region close to your users/servers
   * Enable CDN for frequently accessed files
   * Use multipart uploads for large files

3. **Reliability**:
   * Enable versioning
   * Configure backup/replication
   * Monitor storage metrics
   * Set up alerts for failures

4. **Cost**:
   * Use lifecycle policies
   * Choose appropriate storage class
   * Monitor and optimize access patterns
   * Clean up unused files

## References

* AWS S3: [docs.aws.amazon.com/s3](https://docs.aws.amazon.com/s3)
* Google Cloud Storage: [cloud.google.com/storage/docs](https://cloud.google.com/storage/docs)
* Azure Blob Storage: [docs.microsoft.com/azure/storage/blobs](https://docs.microsoft.com/azure/storage/blobs)