Flexible file upload and attachment library for Elixir

Latest version: 1.1.8 registry icon
Maintenance score
Safety score
Popularity score
Check your open source dependency risks. Get immediate insight about security, stability and licensing risks.
Version Suggest Low Medium High Critical
1.1.8 0 0 0 0 0
1.1.7 0 0 0 0 0
1.1.6 0 0 0 0 0
1.1.5 0 0 0 0 0
1.1.4 0 0 0 0 0
1.1.3 0 0 0 0 0
1.1.2 0 0 0 0 0
1.1.1 0 0 0 0 0
1.1.0 0 0 0 0 0
1.0.1 0 0 0 0 0
1.0.0 0 0 0 0 0
0.0.4 0 0 0 0 0
0.0.3 0 0 0 0 0
0.0.2 0 0 0 0 0
0.0.1 0 0 0 0 0

Latest release:

1.1.8 - This version is safe to use because it has no known security vulnerabilities at this time. Find out if your coding project uses this component and get notified of any reported security vulnerabilities with Meterian-X Open Source Security Platform


Maintain your licence declarations and avoid unwanted licences to protect your IP the way you intended.

Apache-2.0   -   Apache License 2.0

Not a wildcard

Not proprietary

OSI Compliant

Waffle Sponsored by Evrone

Hex.pm Version waffle documentation

Waffle is a flexible file upload library for Elixir

Waffle is a flexible file upload library for Elixir with straightforward integrations for Amazon S3 and ImageMagick.



Add the latest stable release to your mix.exs file, along with the required dependencies for ExAws if appropriate:

defp deps do
    {:waffle, "~> 1.1"},

    # If using S3:
    {:ex_aws, "~> 2.1.2"},
    {:ex_aws_s3, "~> 2.0"},
    {:hackney, "~> 1.9"},
    {:sweet_xml, "~> 0.6"}

Then run mix deps.get in your shell to fetch the dependencies.


After installing Waffle, another two things should be done:

  1. setup a storage provider
  2. define a definition module

Setup a storage provider

Waffle has two built-in storage providers:

  • Waffle.Storage.Local
  • Waffle.Storage.S3

Other available storage providers are supported by the community.

An example for setting up Waffle.Storage.Local:

config :waffle,
  storage: Waffle.Storage.Local,
  asset_host: "http://static.example.com" # or {:system, "ASSET_HOST"}

An example for setting up Waffle.Storage.S3:

config :waffle,
  storage: Waffle.Storage.S3,
  bucket: "custom_bucket",                # or {:system, "AWS_S3_BUCKET"}
  asset_host: "http://static.example.com" # or {:system, "ASSET_HOST"}

config :ex_aws,
  json_codec: Jason
  # any configurations provided by https://github.com/ex-aws/ex_aws

Define a definition module

Waffle requires a definition module which contains the relevant functions to store and retrieve files:

  • Optional transformations of the uploaded file
  • Where to put your files (the storage directory)
  • How to name your files
  • How to secure your files (private? Or publicly accessible?)
  • Default placeholders

This module can be created manually or generated by mix waffle.g automatically.

As an example, we will generate a definition module for handling avatars:

mix waffle.g avatar

This should generate a file at lib/[APP_NAME]_web/uploaders/avatar.ex. Check this file for descriptions of configurable options.


Usage with Ecto

Waffle comes with a companion package for use with Ecto. If you intend to use Waffle with Ecto, it is highly recommended you also add the waffle_ecto dependency. Benefits include:

  • Changeset integration
  • Versioned urls for cache busting (.../thumb.png?v=63601457477)

Other Storage Providers


The basic test suite can be run with without supplying any S3 information:

mix test

In order to test S3 capability, you must have access to an S3/equivalent bucket. For S3 buckets, the bucket must be configured to allow ACLs and it must allow public access.

The following environment variables will be used by the test suite:


After setting these variables, you can run the full test suite with mix test --include s3:true.


Great thanks to Sean Stavropoulos (@stavro) for the original awesome work on the library.

This project is forked from Arc from the version v0.11.0.


Copyright 2019 Boris Kuznetsov me@achempion.com

Copyright 2015 Sean Stavropoulos

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at


Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.