How to Read Image Files from MinIO in Spring Boot

June 11, 2025

#1

If you're building a Spring Boot application that works with image files stored in MinIO, you might be wondering: how can I read and display these images directly in the app—without having users download them?
In this guide, we’ll walk through how to fetch an image from MinIO and stream it directly in a Spring Boot application. This approach is especially useful when you want to show profile pictures, product images, or thumbnails right in your web UI.
We’ll keep things simple and easy to understand, so even if you’re just getting started with Spring Boot and MinIO, you’ll be up and running in no time.

What is MinIO?

MinIO is a high-performance object storage solution that's fully compatible with Amazon S3 APIs. It's lightweight and perfect for local development or private cloud use.
In this example, we assume you already have:

• A running MinIO instance
• An image file uploaded to a MinIO bucket
• A Spring Boot project with basic dependencies

What You’ll Learn

• How to connect to MinIO using the MinIO Java SDK
• How to read an image file as a stream
• How to return the image as an HTTP response in Spring Boot
• How to view the image in a browser or UI

Step 1: Add MinIO Dependency

Make sure to add the MinIO SDK in your pom.xml:

<dependency>
  <groupId>io.minio</groupId>
  <artifactId>minio</artifactId>
  <version>8.5.3</version>
</dependency>

Step 2: Configure MinIO Connection

Set your MinIO details in application.properties:

minio.url=http://localhost:9000
minio.accessKey=minioadmin
minio.secretKey=minioadmin123
minio.bucketName=images

Then, create a configuration class to initialize the MinIO client:

@Configuration
public class MinioConfig {
    @Value("${minio.url}")
    private String url;

    @Value("${minio.accessKey}")
    private String accessKey;

    @Value("${minio.secretKey}")
    private String secretKey;

    @Bean
    public MinioClient minioClient() {
        return MinioClient.builder()
                .endpoint(url)
                .credentials(accessKey, secretKey)
                .build();
    }
}

Step 3: Create a Service to Read Images

This service will fetch the file stream from MinIO:

@Service
public class MinioService {
    @Value("${minio.bucketName}")
    private String bucketName;

    @Autowired
    private MinioClient minioClient;

    public InputStream getImage(String fileName) throws Exception {
        return minioClient.getObject(
                GetObjectArgs.builder()
                        .bucket(bucketName)
                        .object(fileName)
                        .build()
        );
    }
}

Step 4: Create a Controller to Stream the Image

This controller method will serve the image to the browser without downloading it.

@RestController
@RequestMapping("/images")
public class ImageController {

    @Autowired
    private MinioService minioService;

    @GetMapping("/{filename}")
    public ResponseEntity<byte[]> getImage(@PathVariable String filename) {
        try (InputStream inputStream = minioService.getImage(filename)) {
            byte[] imageBytes = inputStream.readAllBytes();

            HttpHeaders headers = new HttpHeaders();
            headers.setContentType(MediaType.IMAGE_JPEG); // or PNG depending on your file
            headers.setContentLength(imageBytes.length);

            return new ResponseEntity<>(imageBytes, headers, HttpStatus.OK);
        } catch (Exception e) {
            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
        }
    }
}

Tip: Adjust the MediaType based on your file type (e.g., MediaType.IMAGE_PNG for PNGs).

Step 5: Test in Browser

Once your application is running, try accessing your image in the browser like this:

http://localhost:8080/images/sample.jpg

If the image exists in your MinIO bucket, it will load directly in the browser tab—no download popup!

Common Use Cases

• User profile pictures
• Product images in an e-commerce site
• Document previews (thumbnails)

This method allows your frontend to request images via simple URLs, and your backend streams the data securely and efficiently.

Best Practices

• Use environment variables for MinIO credentials in production
• Set proper content type headers
• Catch and handle errors gracefully (e.g., file not found)
• Consider caching frequently accessed images for better performance