Scalable file storage fields for your Django models.

The files are stored on disk in a tree structure that ensures not too many files end up in the same directory, to maintain things fast when the number of files grows. The structure is as follows:


Where NWoZK3kTsExUV00Ywo1G5jlUKKs is a hash made from the model instance’s primary key.


Simply add FileStorageField to your models:

from django.db import models
from fsfield import FileStorageField

class MyModel(models.Model):

    field = FileStorageField()

The field then acts as a django.db.models.fields.TextField:

>>> obj = MyModel.objects.create()
>>> obj.field = "foo"
>>> obj = MyModel.objects.get(
>>> obj.field

You can customize the way data is loaded and saved with the load and dump parameters:

from django.db import models
from django.utils import simplejson as json
from fsfield import FileStorageField

class MyModel(models.Model):

    json_field = FileStorageField(load=json.load, dump=json.dump)

json_field can then be used to store JSON data directly:

>>> obj = MyModel.objects.create()
>>> obj.json_field = {"data": 1}
>>> obj.json_field
{"data": 1}

FileStorageField reference


A string containing the Python path of the Storage class to use. The default is ''.
A tuple containing positional and keyword arguments passed to the storage class constructor. Default is ((), {}).
The number of sub paths used to distribute the files in directories.


changing this setting will make old files unreachable. The default of 5 should be enough for most uses (average 93 files per directory for 100 billion files)

Project Versions

Table Of Contents

This Page