How to Download File in Spring Boot: Simple Guide

In Spring Boot, you can download a file by creating a controller method that returns a ResponseEntity with the file's bytes and sets the Content-Disposition header to attachment. This tells the browser to download the file instead of displaying it.

Syntax

The basic syntax to download a file in Spring Boot involves returning a ResponseEntity with the file data as a byte array or InputStreamResource. You must set HTTP headers like Content-Type and Content-Disposition to indicate the file type and that it should be downloaded.

• ResponseEntity: The HTTP response with file bytes.
• HttpHeaders: To set metadata like filename and content type.
• Content-Disposition: Set to attachment; filename="file.ext" to trigger download.

java

return ResponseEntity.ok()
    .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=example.txt")
    .contentType(MediaType.APPLICATION_OCTET_STREAM)
    .body(fileBytes);

Example

This example shows a Spring Boot controller method that lets users download a text file named example.txt. It reads the file from the resources folder and sends it as a downloadable response.

java

import org.springframework.core.io.ClassPathResource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.io.IOException;
import java.nio.file.Files;

@RestController
public class FileDownloadController {

    @GetMapping("/download")
    public ResponseEntity<byte[]> downloadFile() throws IOException {
        ClassPathResource resource = new ClassPathResource("example.txt");
        byte[] fileData = Files.readAllBytes(resource.getFile().toPath());

        return ResponseEntity.ok()
                .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=example.txt")
                .contentType(MediaType.APPLICATION_OCTET_STREAM)
                .body(fileData);
    }
}

Output

When you visit http://localhost:8080/download, the browser will prompt to download a file named example.txt containing the file's content.

Common Pitfalls

• Not setting Content-Disposition header causes the browser to display the file instead of downloading.
• Using incorrect Content-Type may cause the file to open in the browser.
• Reading large files fully into memory can cause performance issues; consider streaming for big files.
• For files inside JARs, use InputStream instead of File to read resources.

java

/* Wrong way: Missing Content-Disposition header */
return ResponseEntity.ok()
    .contentType(MediaType.APPLICATION_OCTET_STREAM)
    .body(fileBytes);

/* Right way: Include Content-Disposition header */
return ResponseEntity.ok()
    .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=example.txt")
    .contentType(MediaType.APPLICATION_OCTET_STREAM)
    .body(fileBytes);

Quick Reference

• Use ResponseEntity to send file bytes.
• Set Content-Disposition to attachment; filename="yourfile.ext".
• Set Content-Type to match the file type or use application/octet-stream for generic binary.
• For large files, consider streaming with InputStreamResource.

Key Takeaways

Always set the Content-Disposition header to attachment with a filename to trigger file download.

Use ResponseEntity with file bytes or InputStreamResource to send the file content.

Set the Content-Type header appropriately to inform the browser about the file type.

Avoid loading large files fully into memory; use streaming for better performance.

For files inside JARs, read resources as streams, not as files.