# Django 3.2.12 documentation

# File storage API

## Getting the current storage class

Django provides two convenient ways to access the current storage class:

class `DefaultStorage`

  `DefaultStorage` provides lazy access to the current default storage system as defined by `DEFAULT_FILE_STORAGE`. `DefaultStorage` uses `get_storage_class()` internally.

`get_storage_class`(import_path=None)

  Returns a class or module which implements the storage API.

  When called without the `import_path` parameter `get_storage_class` will return the current default storage system as defined by `DEFAULT_FILE_STORAGE`. If `import_path` is provided, `get_storage_class` will attempt to import the class or module from the given path and will return it if successful. An exception will be raised if the import is unsuccessful.

## The `FileSystemStorage` class

class `FileSystemStorage`(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)

  The `FileSystemStorage` class implements basic file storage on a local filesystem. It inherits from `Storage` and provides implementations for all the public methods thereof.

  `location`

    Absolute path to the directory that will hold the files. Defaults to the value of your `MEDIA_ROOT` setting.

  `base_url`

    URL that serves the files stored at this location. Defaults to the value of your `MEDIA_URL` setting.

  `file_permissions_mode`

    The file system permissions that the file will receive when it is saved. Defaults to `FILE_UPLOAD_PERMISSIONS`.

  `directory_permissions_mode`

    The file system permissions that the directory will receive when it is saved. Defaults to `FILE_UPLOAD_DIRECTORY_PERMISSIONS`.

  Note

  The `FileSystemStorage.delete()` method will not raise an exception if the given file name does not exist.

  `get_created_time`(name)

    Returns a `datetime` of the system’s ctime, i.e. `os.path.getctime()`. On some systems (like Unix), this is the time of the last metadata change, and on others (like Windows), it’s the creation time of the file.

Changed in Django 3.1:

Support for `pathlib.Path` was added to the `FileSystemStorage.save()` method.

## The `Storage` class

class `Storage`

  The `Storage` class provides a standardized API for storing files, along with a set of default behaviors that all other storage systems can inherit or override as necessary.

  Note

  When methods return naive `datetime` objects, the effective timezone used will be the current value of `os.environ['TZ']`; note that this is usually set from Django’s `TIME_ZONE`.

  `delete`(name)

    Deletes the file referenced by `name`. If deletion is not supported on the target storage system this will raise `NotImplementedError` instead.

  `exists`(name)

    Returns `True` if a file referenced by the given name already exists in the storage system, or `False` if the name is available for a new file.

  `get_accessed_time`(name)

    Returns a `datetime` of the last accessed time of the file. For storage systems unable to return the last accessed time this will raise `NotImplementedError`.

    If `USE_TZ` is `True`, returns an aware `datetime`, otherwise returns a naive `datetime` in the local timezone.

  `get_alternative_name`(file_root, file_ext)

    Returns an alternative filename based on the `file_root` and `file_ext` parameters, an underscore plus a random 7 character alphanumeric string is appended to the filename before the extension.

  `get_available_name`(name, max_length=None)

    Returns a filename based on the `name` parameter that’s free and available for new content to be written to on the target storage system.

    The length of the filename will not exceed `max_length`, if provided. If a free unique filename cannot be found, a `SuspiciousFileOperation` exception will be raised.

    If a file with `name` already exists, `get_alternative_name()` is called to obtain an alternative name.

  `get_created_time`(name)

    Returns a `datetime` of the creation time of the file. For storage systems unable to return the creation time this will raise `NotImplementedError`.

    If `USE_TZ` is `True`, returns an aware `datetime`, otherwise returns a naive `datetime` in the local timezone.

  `get_modified_time`(name)

    Returns a `datetime` of the last modified time of the file. For storage systems unable to return the last modified time this will raise `NotImplementedError`.

    If `USE_TZ` is `True`, returns an aware `datetime`, otherwise returns a naive `datetime` in the local timezone.

  `get_valid_name`(name)

    Returns a filename based on the `name` parameter that’s suitable for use on the target storage system.

  `generate_filename`(filename)

    Validates the `filename` by calling `get_valid_name()` and returns a filename to be passed to the `save()` method.

    The `filename` argument may include a path as returned by `FileField.upload_to`. In that case, the path won’t be passed to `get_valid_name()` but will be prepended back to the resulting name.

    The default implementation uses `os.path` operations. Override this method if that’s not appropriate for your storage.

  `listdir`(path)

    Lists the contents of the specified path, returning a 2-tuple of lists; the first item being directories, the second item being files. For storage systems that aren’t able to provide such a listing, this will raise a `NotImplementedError` instead.

  `open`(name, mode='rb')

    Opens the file given by `name`. Note that although the returned file is guaranteed to be a `File` object, it might actually be some subclass. In the case of remote file storage this means that reading/writing could be quite slow, so be warned.

  `path`(name)

    The local filesystem path where the file can be opened using Python’s standard `open()`. For storage systems that aren’t accessible from the local filesystem, this will raise `NotImplementedError` instead.

  `save`(name, content, max_length=None)

    Saves a new file using the storage system, preferably with the name specified. If there already exists a file with this name `name`, the storage system may modify the filename as necessary to get a unique name. The actual name of the stored file will be returned.

    The `max_length` argument is passed along to `get_available_name()`.

    The `content` argument must be an instance of `django.core.files.File` or a file-like object that can be wrapped in `File`.

  `size`(name)

    Returns the total size, in bytes, of the file referenced by `name`. For storage systems that aren’t able to return the file size this will raise `NotImplementedError` instead.

  `url`(name)

    Returns the URL where the contents of the file referenced by `name` can be accessed. For storage systems that don’t support access by URL this will raise `NotImplementedError` instead.