pip install django-rustfs

Why django-rustfs?

You can already use RustFS with Django via django-storages + boto3. So why another package?

The Problem

django-storages is great for AWS S3, but using it with RustFS means:

• Pretending RustFS is AWS (AWS_S3_ENDPOINT_URL, AWS_ACCESS_KEY_ID...)
• Configuring 10+ settings you do not need
• No built-in health checks or bucket setup tools
• Writing custom code for static files

The Solution

django-rustfs is purpose-built for RustFS:

Bottom line: If you are using RustFS, django-rustfs removes the mental overhead of pretending you are configuring AWS S3.

Installation

pip install django-rustfs

Requirements:

• Python 3.9+
• Django 4.2 through 6.1
• boto3 1.28+

Django compatibility

Django 6.1 support is tested against Python 3.12, 3.13, and 3.14 in CI.

Quick Start

1. Add to Installed Apps

# settings.py

INSTALLED_APPS = [
    # ... your apps
    "django_rustfs",
]

2. Configure Connection

# settings.py

# Required
RUSTFS_ENDPOINT = "http://localhost:9000"
RUSTFS_ACCESS_KEY = "your-access-key"
RUSTFS_SECRET_KEY = "your-secret-key"

# Optional (defaults shown)
RUSTFS_BUCKET_NAME = "django-media"
RUSTFS_AUTO_CREATE_BUCKET = True

3. Set as Default Storage

Django 4.2+ (recommended):

# settings.py

STORAGES = {
    "default": {
        "BACKEND": "django_rustfs.storage.RustFSStorage",
    },
    "staticfiles": {
        "BACKEND": "django_rustfs.storage.RustFSStaticStorage",
    },
}

Django < 4.2:

DEFAULT_FILE_STORAGE = "django_rustfs.storage.RustFSStorage"
STATICFILES_STORAGE = "django_rustfs.storage.RustFSStaticStorage"

4. Initialize Buckets

python manage.py rustfs_init_buckets

5. Verify Everything Works

python manage.py rustfs_health

Output:

🔍 Checking RustFS health...
   Endpoint: http://localhost:9000
   Bucket:   django-media

  ✅ Bucket 'django-media' is accessible
     Response time: 12.3ms
  ✅ List operation works (0 objects visible)

  🧪 Running upload/download roundtrip test...
  ✅ Upload/download roundtrip successful

✅ RustFS health check completed successfully!

Configuration

All settings use the RUSTFS_ prefix for clarity.

Required Settings

Optional Settings

Management Commands

rustfs_health

Check connectivity, authentication, and run an upload/download roundtrip test:

python manage.py rustfs_health
python manage.py rustfs_health --bucket=my-bucket

rustfs_init_buckets

Create and configure RustFS buckets:

python manage.py rustfs_init_buckets              # Create all buckets
python manage.py rustfs_init_buckets --bucket=X   # Create specific bucket
python manage.py rustfs_init_buckets --public     # Make buckets public
python manage.py rustfs_init_buckets --dry-run    # Preview changes

Advanced Usage

Per-Field Storage Configuration

Configure different buckets for different model fields:

from django.db import models
from django_rustfs.storage import RustFSStorage

# Private storage for documents
private_storage = RustFSStorage(
    bucket_name="user-documents",
    default_acl="private",
)

# Public storage for avatars
public_storage = RustFSStorage(
    bucket_name="public-avatars",
    default_acl="public-read",
    presign_urls=False,
)


class UserProfile(models.Model):
    avatar = models.ImageField(storage=public_storage, upload_to="avatars/")
    documents = models.FileField(storage=private_storage, upload_to="docs/")

Direct Browser Uploads (Presigned POST)

Let browsers upload directly to RustFS without going through your Django server:

from django_rustfs.storage import RustFSStorage

storage = RustFSStorage()
post_data = storage.get_presigned_post_url(
    name="uploads/user123/photo.jpg",
    expires_in=600,
)

# Returns:
# {
#   "url": "http://localhost:9000/django-media",
#   "fields": {
#     "key": "uploads/user123/photo.jpg",
#     "AWSAccessKeyId": "...",
#     "policy": "...",
#     "signature": "..."
#   }
# }

Object Metadata Access

storage = RustFSStorage()
meta = storage.get_object_metadata("uploads/photo.jpg")

print(meta["etag"])  # "d41d8cd98f00b204e9800998ecf8427e"
print(meta["content_length"])  # 2048
print(meta["storage_class"])  # "STANDARD"
print(meta["version_id"])  # "uuid-v1"

Copy Objects

storage.copy_object("uploads/photo.jpg", "backups/photo-backup.jpg")

Architecture

┌─────────────┐      ┌─────────────────┐      ┌─────────────┐
│   Django    │──────│  django-rustfs  │──────│    boto3    │
│             │      │  (this package) │      │  (AWS SDK)  │
└─────────────┘      └────────┬────────┘      └──────┬──────┘
                              │                       │
                              └────── HTTP/HTTPS ─────┘
                                      │
                                ┌─────────────┐
                                │    RustFS    │
                                │    Server    │
                                └─────────────┘

django-rustfs uses boto3 to communicate with RustFS. RustFS is fully S3-compatible, so the AWS SDK works out of the box - we just wrap it in a purpose-built API.

Development

Setup

git clone https://github.com/CasualEngineerZombie/django-rustfs.git
cd django-rustfs
pip install -e ".[dev]"

Running Tests

pytest

With coverage:

pytest --cov=django_rustfs --cov-report=html

Code Quality

ruff check .          # Linting
ruff format .         # Formatting
mypy django_rustfs    # Type checking

Project Structure

django-rustfs/
├── django_rustfs/          # Main package
│   ├── storage.py          # Core storage backend
│   ├── conf.py             # Settings configuration
│   └── management/         # Management commands
│       └── commands/
│           ├── rustfs_health.py
│           └── rustfs_init_buckets.py
├── tests/                  # Test suite
├── .github/workflows/      # CI/CD
├── pyproject.toml          # Package config
└── README.md               # This file

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Quick start for contributors:

git clone https://github.com/CasualEngineerZombie/django-rustfs.git
cd django-rustfs
pip install -e ".[dev]"
pytest

Roadmap

• RustFS-native features - Expose RustFS-specific capabilities (replication, lifecycle rules, event notifications)
• Django Admin integration - View bucket contents and storage statistics
• Management commands - sync_to_rustfs, sync_from_rustfs, clean_orphaned
• Async support - aioboto3-based async storage backend
• URL caching - Cache presigned URLs with Django's cache framework
• Multipart upload - Resumable multipart uploads for large files
• Streaming responses - Memory-efficient FileResponse wrapper

License

Apache 2.0 - see LICENSE file.