gradle-download-task: fetching files from a Gradle build with progress output

The plugin that big build systems already depend on

gradle-download-task is a Gradle plugin whose stated purpose is to download files in your build script with progress and in parallel. The project lists who uses it, and the list is the best argument for adopting it. Facebook's React Native and Hermes are named, as is libGDX and the T. J. Watson Libraries for Analysis. Underneath that there is a count of more than six thousand open source projects using the plugin id de.undercouch.download, and the project asks you to comment on an issue if you want to be listed. The plugin is Apache-2.0 licensed with the text in LICENSE.txt at the repository root, it is written in Java, and the repository carries its own Gradle wrapper, a .tool-versions file and a codecov.yml for coverage reporting.

Applying the plugin and declaring a Download task

Using the plugin takes two steps. First you apply it in the plugins block.

plugins {
    id "de.undercouch.download" version "5.7.0"
}

Then you declare a task of type Download, naming where the file comes from and where it should go.

task downloadFile(type: Download) {
    src 'http://www.example.com/index.html'
    dest layout.buildDirectory
}

The src and dest properties are both required. The interesting design choice is that dest points at layout.buildDirectory, so the download lands inside the build directory rather than in the source tree, which keeps a fetched file out of version control and lets a clean task remove it.

By default it always downloads, which is usually wrong

Here is the setting that will save you a broken build. By default the plugin always performs a download even if the destination file already exists, so every build re-fetches the file, and if the server is slow or unreachable the build fails for a file you already had. The overwrite flag turns that behaviour off.

task downloadFile(type: Download) {
    src 'http://www.example.com/index.html'
    dest layout.buildDirectory
    overwrite false
}

The same property exists on the task and on the extension, and the task documentation also lists a quiet flag, which is true if progress information should not be displayed and defaults to false, meaning the progress output is on unless you turn it off. So the plugin gives you progress like Gradle's own artifact resolution by default, and silence when you want it.

The download extension for use inside any task

The Download task is not the only entry point. There is also a download extension that lets you retrieve a file anywhere in your build script, which is what you want when the download is one step inside a larger task rather than a task of its own.

task myTask {
    doLast {
        // do something ...
        // ... then download a file
        download.run {
            src 'http://www.example.com/index.html'
            dest layout.buildDirectory
            overwrite false
        }
        // ... do something else
    }
}

The extension also has a runAsync method that downloads a file asynchronously and returns a CompletableFuture that either completes successfully or exceptionally depending on whether the download finished or failed. The project insists on one point here: always wait for the result of the CompletableFuture, otherwise errors might get lost. That is a real trap, because an unawaited failed future in a build script produces a build that appears to succeed and then fails later for no visible reason.

onlyIfModified avoids re-downloading unchanged files

There is a smarter variant of the overwrite flag. The onlyIfModified option makes the task fetch the file only if it changed on the server.

task downloadFile(type: Download) {
    src 'http://www.example.com/index.html'
    dest layout.buildDirectory
    onlyIfModified true
}

The project is careful about the conditions here, and you should be too. The example only works if the server supports the If-Modified-Since request header and provides a Last-Modified timestamp in its response. If the server supports entity tags instead, you can use onlyIfModified together with useETag. In other words, this is a conditional request, and its value depends entirely on the server cooperating. Against a static file host that returns no Last-Modified header, the option buys you nothing and you are back to overwrite false.

Parallel downloads need a directory as the destination

The task can fetch several files at once, which is where the parallel download support comes in, and there is a rule you will hit if you ignore it.

task downloadMultipleFiles(type: Download) {
    src([
        'http://www.example.com/index.html',
        'http://www.example.com/test.html'
    ])
    dest layout.buildDirectory
}

If you download multiple files you have to specify a directory as the destination, otherwise the plugin will fail. The same task also supports downloading a whole directory when the server provides a simple directory listing, using Ivy's ApacheURLLister to enumerate the files and then handing them to the download extension, and the plugin can be combined with Gradle's built-in ZIP support to fetch and unpack an archive in two linked tasks, one of type Download and one of type Copy reading from zipTree.

Gradle and Java versions, and the older fallback line

The compatibility story is stated plainly. The plugin requires Gradle 5.x or higher and Java 8 or higher, and it has been successfully tested with Gradle 5.0 up to 9.3.1, with the expectation that it should work with newer versions as well. If you need to run it with Gradle 2.x up to 4.x or with Java 7, the project points you to gradle-download-task version 4.1.2, so the old line is still maintained as a separate artifact rather than dropped. The release history shows how the current line has moved: version 5.7.0 on 2026-02-03, 5.6.0 on 2024-02-29 and 5.5.0 on 2023-08-27, with the last push to the repository on 2026-10-17. The examples directory is split into groovy and kotlin samples, so you can see the task used from both build script languages.

Editorial conclusion

gradle-download-task fits a Gradle build that needs to fetch a file, a toolchain, a list of assets or an archive at build time and wants the output to look like Gradle's own artifact resolution rather than a silent curl, and it fits teams that value the fact that the plugin is used by React Native, Hermes, libGDX and WALA. It does not fit a build that must not depend on the network, since the task fetches over HTTP on every run unless you set overwrite false, and it does not fit a project stuck on an old toolchain, because the plugin needs Gradle 5.x or newer and Java 8 or newer, with version 4.1.2 being the fallback for Gradle 2.x through 4.x or Java 7. Before you add it, check that the server you fetch from honours If-Modified-Since and returns a Last-Modified timestamp if you intend to use onlyIfModified, decide whether you want a directory as the destination when downloading several files since the task fails otherwise, and read the properties table rather than relying on defaults, because overwrite defaults to true and quiet defaults to false.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. michel-kraemer/gradle-download-task on GitHub
4. README
5. Releases