Skip to content
Chainable file upload api for express
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib Expose express middleware functionality
.travis.yml Fixed the npm install command.
package.json Make gm dependency mandatory


Express-Upload exposes a chainable/fluent API to process uploaded files in express. In case you're searching for a solution focused on processing image uploads, take a look at express-upload-resizer.

Build Status


$ npm install express-upload


var upload = require('express-upload');

// ..

    .gm(function(gm) {
        return gm.resize(false, 100);
    .to(['public', 'images'])
    .exec(req.files.displayImage, function(err, file) {
        // further process file

Processing Chains

After creating an Upload object by calling upload() the upload object exposes API methods


Restricts files accepted by upload to specified mime types. Mime types can be specified as strings, array of strings, regex or array of regex. In case match fails an err object is passed to the exec callback field accept set to true.


Accept mp4, ogg and jpeg files in upload

  accept(['audio/mp4', 'audio/ogg', 'image/jpeg'])

Accept only mp4


Accept all audio mime types p



Moves files from temp express upload location to the target location. The to processor modifies file.path and fields of the original express upload file to point to the moved upload file. to will use any given file extension from the original A target directory is expected as argument, in case an array of strings is passed this array will be joined via path.join.


Moves uploaded files to public/images

  to(['public', 'images'])

Moves uploaded files to public/images



Allows uploaded files to be processed via GraphicsMagick or ImageMagick. See gm page for using gm.


Resize an uploaded image to height of 100 with aspect ration

  gm(function(gm) {
      return gm.resize(false, 100);


Generic handler to pass custom transformation code in the processing chain. Functions passed to process must have the signature

  fn(file, cb)

Where file is the processed upload file and cb is the callback.


Executes a processing chain. Processing chains are reusable and may be executed multiple times. In case the file is not part of the upload or is empty an err is passed to the callback with a field noFile set to true.


Instead of executing and managing upload file processing in your routes, express-upload can be used as middleware in express. Any processing errors (no file, file type not accepted,...) are stored in a err property of the file to upload.


  // Build an upload instance but don't execute it right now
  var uploadDefinition = upload()
      .gm(function(gm) {
          return gm.resize(false, 100);
      .to(['public', 'images']);

  // Define a middleware for handling image upload'/middleware', uploadDefinition.middleware('displayImage'), routes.uploadUsingMiddleware);

In case an error would occur when uploading req.files.displayImage, req.files.displayImage.err would be set to an Error object.

Show me some example

Simple upload.

Something went wrong with that request. Please try again.