class Shrine::Storage::FileSystem

  1. lib/shrine/storage/file_system.rb
Superclass: Object

The FileSystem storage handles uploads to the filesystem, and it is most commonly initialized with a “base” folder and a “prefix”:

require "shrine/storage/file_system"

storage ="public", prefix: "uploads")
storage.url("image.jpg") #=> "/uploads/image.jpg"

This storage will upload all files to “public/uploads”, and the URLs of the uploaded files will start with “/uploads/*”. This way you can use FileSystem for both cache and store, one having the prefix “uploads/cache” and other “uploads/store”. If you're uploading files to the public directory itself, you need to set :prefix to "/":

storage ="public", prefix: "/") # no prefix
storage.url("image.jpg") #=> "/image.jpg"

You can also initialize the storage just with the “base” directory, and then the FileSystem storage will generate absolute URLs to files:

storage =
storage.url("image.jpg") #=> "/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/image.jpg"

In general you can always retrieve path to the file using #path:

storage.path("image.jpg") #=> #<Pathname:public/image.jpg>


It's generally a good idea to serve your files via a CDN, so an additional :host option can be provided to #url:

storage ="public", prefix: "uploads")
storage.url("image.jpg", host: "")
#=> ""

If you're not using a CDN, it's recommended that you still set :host to your application's domain (at least in production).

The :host option can also be used wihout :prefix, and is useful if you for example have files located on another server:

storage ="/opt/files")
storage.url("image.jpg", host: "http://943.23.43.1")
#=> "http://943.23.43.1/opt/files/image.jpg"

Clearing cache

If you're using FileSystem as cache, you will probably want to periodically delete old files which aren't used anymore. You can run something like this periodically:

file_system = Shrine.storages[:cache]
file_system.clear!(older_than: - 7*24*60*60) # delete files older than 1 week


The storage sets the default UNIX permissions to 0644 for files and 0755 for directories, but you can change that:"directory", permissions: 0644)"directory", directory_permissions: 0755)


Note that Heroku has a read-only filesystem, and doesn't allow you to upload your files to the “public” directory, you can however upload to “tmp” directory:"tmp/uploads")

Note that this approach has a couple of downsides. For example, you can only use it for cache, since Heroku wipes this directory between app restarts. This also means that deploying the app can cancel someone's uploading if you're using backgrounding. Also, by default you cannot generate URLs to files in the “tmp” directory, but you can with the download_endpoint plugin.


Public Class methods

new (directory, prefix: nil, host: nil, clean: true, permissions: 0644, directory_permissions: 0755)

Initializes a storage for uploading to the filesystem.


The directory relative to directory to which files will be stored, and it is included in the URL.


The UNIX permissions applied to created files. Can be set to nil, in which case the default permissions will be applied. Defaults to 0644.


The UNIX permissions applied to created directories. Can be set to nil, in which case the default permissions will be applied. Defaults to 0755.


By default empty folders inside the directory are automatically deleted, but if it happens that it causes too much load on the filesystem, you can set this option to false.

[show source]
# File lib/shrine/storage/file_system.rb, line 108
def initialize(directory, prefix: nil, host: nil, clean: true, permissions: 0644, directory_permissions: 0755)
  Shrine.deprecation("The :host option to Shrine::Storage::FileSystem#initialize is deprecated and will be removed in Shrine 3. Pass :host to FileSystem#url instead, you can also use default_url_options plugin.") if host

  if prefix
    @prefix = Pathname(relative(prefix))
    @directory = Pathname(directory).join(@prefix).expand_path
    @directory = Pathname(directory).expand_path

  @host = host
  @permissions = permissions
  @directory_permissions = directory_permissions
  @clean = clean

  unless @directory.exist?
    @directory.chmod(directory_permissions) if directory_permissions

Public Instance methods

clear! (older_than: nil)

Deletes all files from the directory. If :older_than is passed in (a Time object), deletes all files which were last modified before that time.

[show source]
# File lib/shrine/storage/file_system.rb, line 189
def clear!(older_than: nil)
  if older_than
    # add trailing slash to make it work with symlinks
    Pathname("#{directory}/").find do |path|
      if path.file? && path.mtime < older_than
        clean(path) if clean?
delete (id)

Delets the file, and by default deletes the containing directory if it's empty.

[show source]
# File lib/shrine/storage/file_system.rb, line 169
def delete(id)
  path = path(id)
  clean(path) if clean?
rescue Errno::ENOENT
exists? (id)

Returns true if the file exists on the filesystem.

[show source]
# File lib/shrine/storage/file_system.rb, line 163
def exists?(id)
method_missing (name, *args, &block)

Catches the deprecated #download method.

[show source]
# File lib/shrine/storage/file_system.rb, line 209
def method_missing(name, *args, &block)
  case name
  when :download then deprecated_download(*args, &block)
movable? (io, id)

Returns true if the file is a File or a UploadedFile uploaded by the FileSystem storage.

[show source]
# File lib/shrine/storage/file_system.rb, line 151
def movable?(io, id)
  io.respond_to?(:path) ||
    (io.is_a?(UploadedFile) &&
move (io, id, shrine_metadata: {}, **upload_options)

Moves the file to the given location. This gets called by the moving plugin.

[show source]
# File lib/shrine/storage/file_system.rb, line 139
def move(io, id, shrine_metadata: {}, **upload_options)
  if io.respond_to?(:path) io.path, path!(id)
  else, path!(id) if
  path(id).chmod(permissions) if permissions
open (id, **options, &block)

Opens the file on the given location in read mode. Accepts additional arguments.

[show source]
# File lib/shrine/storage/file_system.rb, line 158
def open(id, **options, &block)
  path(id).open(binmode: true, **options, &block)
path (id)

Returns the full path to the file.

[show source]
# File lib/shrine/storage/file_system.rb, line 204
def path(id)
  directory.join(id.gsub("/", File::SEPARATOR))
upload (io, id, shrine_metadata: {}, **upload_options)

Copies the file into the given location.

[show source]
# File lib/shrine/storage/file_system.rb, line 130
def upload(io, id, shrine_metadata: {}, **upload_options)
  bytes_copied = IO.copy_stream(io, path!(id))
  path(id).chmod(permissions) if permissions

  shrine_metadata["size"] ||= bytes_copied
url (id, host:, **options)

If prefix is not present, returns a path composed of directory and the given id. If prefix is present, it excludes the directory part from the returned path (e.g. directory can be set to “public” folder). Both cases accept a :host value which will be prefixed to the generated path.

[show source]
# File lib/shrine/storage/file_system.rb, line 181
def url(id, host:, **options)
  path = (prefix ? relative_path(id) : path(id)).to_s
  host ? host + path : path