Download a file

Download an object's bytes. Optional transform routes through the image renderer.

Fetch the raw bytes of path from the bucket. With transform:, the request is routed through render/image/authenticated and the keys are passed as query params; without it, the request hits object/.

Signature

supabase.storage.from(bucket_id).download(path,transform: nil,query_params: nil)

Parameters

Name	Type	Required	Description
`path`	String	Required	Object path inside the bucket. Leading "/" is stripped.
`transform`	Hash	Optional	Image-render options. Known keys: :height, :width, :resize ("cover"/"contain"/"fill"), :format ("origin"), :quality (Integer). Unknown keys emit Kernel.warn but are still forwarded.
`query_params`	Hash	Optional	Arbitrary extra query parameters appended to the request URL (merged after transform — explicit keys win on conflict).

Returns

String

Raw response body bytes. Encoding is ASCII-8BIT for binary objects. Returned directly from Faraday — caller is responsible for writing to disk, decoding, or streaming.

Example — write bytes to disk

bytes = supabase.storage.from("avatars").download("people/ada.png")
File.binwrite("./ada.png", bytes)

Example — image transform (resize on the fly)

thumb = supabase.storage.from("avatars").download(
  "people/ada.png",
  transform: { width: 64, height: 64, resize: "cover", quality: 80 }
)
File.binwrite("./ada-64.png", thumb)

Example — extra query params

# Adds ?cb=20260612 to the request URL — useful for cache-busting via a CDN.
supabase.storage.from("avatars").download(
  "people/ada.png",
  query_params: { "cb" => "20260612" }
)

Unknown transform: keys are forwarded to storage-api (so server-only flags still work) but emit a one-line Kernel#warn to catch typos like :hieght early.