MinIO in WSL: Local Object Storage, Persistent Data, and Client Paths

MinIO can provide an S3-compatible object-storage endpoint for application development and integration tests inside a WSL distribution. A useful lab can exercise buckets, object APIs, SDK configuration, and local service discovery without requiring a remote account. It does not turn one WSL virtual disk into a highly available storage system: a single process, one host, and one backing filesystem remain one failure domain.

The most important WSL design choice is where the server’s data directory lives. Keep mutable database-like object data inside the distribution’s Linux filesystem, such as a path under $HOME or /var/lib, rather than on /mnt/c. Microsoft documents that Linux workloads generally perform better on the Linux filesystem than across the Windows-mounted filesystem boundary. This also keeps Linux ownership and permission semantics predictable.

Define the lab boundary and storage path

Use a dedicated directory for MinIO state and verify its mount before starting the server:

mkdir -p "$HOME/minio-lab/data"
df -T "$HOME/minio-lab/data"
stat -c '%U:%G %a %n' "$HOME/minio-lab/data"

The path should resolve to the distribution’s Linux filesystem. Do not point it at a Windows share or a synced folder and then treat the result as a production data path. A Windows backup or file synchronization tool may observe the VHDX differently from an application-consistent object-store backup. Keep test objects disposable unless a separate backup and restore process is in place.

MinIO’s server documentation requires the storage directory to be empty when a new server instance first starts. Check the directory and use a new, empty path rather than reusing data from an unknown installation. Never run two MinIO processes against the same directory. If data from a previous test must be retained, identify the server version and follow the project’s upgrade or migration guidance instead of deleting internal files.

Install and start one local instance

Check the project’s maintenance status before installing

As of October 4, 2026, MinIO’s minio/minio Community Server repository is archived and read-only. Its own README says the Community Edition is source-only, that historical prebuilt binaries are no longer maintained, and that building Community Edition from source for production is at the user’s risk. The separate documentation repository says the hosted Community Server documentation was removed in October 2025 and is no longer actively developed. Do not treat the old binary download or the former Linux installation pages as a maintained, security-patched distribution.

For a new production service, do not deploy an unmaintained Community Server build. Review the vendor’s currently supported offering, license, and security-update terms, or select another actively maintained object store. If you deliberately reproduce the historical Community Server in a disposable lab, review and pin an exact source commit, record the Go toolchain and resulting build hash, and keep it isolated from sensitive data and untrusted networks. Do not use a moving latest reference or assume an old binary will receive fixes.

The commands below are server-operation examples for that explicitly bounded lab, not installation or production-hardening instructions.

For an isolated evaluation, the server interface accepts a directory argument. An example with explicit ports is:

minio server --address 127.0.0.1:9000 --console-address 127.0.0.1:9001 "$HOME/minio-lab/data"

This command is suitable only when the process can bind to the loopback address in your WSL networking mode and the Windows client reaches it through the documented host path. If the address is unavailable or the Windows side cannot connect, inspect WSL networking mode and listener state before binding to every interface. Do not expose an object API publicly just to make a browser reach the console.

MinIO distinguishes the S3 API port from the web console. If no static console address is specified, the server can select a dynamic port and report it in startup output. Pinning a local console port makes development tools easier to configure, but port collisions must be checked first. Keep the terminal output because it reports startup state and endpoint information.

Configure credentials without baking them into a script

MinIO requires root credentials for a new server. Supply them through an interactive secret store or protected environment management rather than committing them to shell history, a repository, or a .wslconfig file. For a short-lived local shell, environment variables can be exported and cleared after use, but a persistent service needs a protected secret mechanism and an explicit owner.

Do not use demonstration credentials copied from an unrelated guide. Do not reuse a production credential in a local lab. If the local MinIO endpoint is accessible from other Windows processes or network interfaces, the secret boundary includes those clients too. Restrict listener addresses to the intended development path, and do not assume that a WSL NAT address is private from every host process.

Configure the MinIO client with the actual endpoint and credentials using the client version’s documented syntax. Keep bucket names, endpoint URL, region behavior, and test credentials in local configuration that is excluded from source control. The client alias is a connection convenience; it does not create network isolation or make the endpoint durable.

Verify API behavior from both sides

From Linux, confirm the process and listener:

ps -ef | grep '[m]inio server'
ss -ltnp | grep -E ':(9000|9001)'
mc alias set wsl-lab http://127.0.0.1:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"
mc admin info wsl-lab

Use the exact client syntax supported by the installed mc release and avoid printing secrets into shared logs. admin info provides a server status view, but a live response does not prove that data survives a restart or that a backup is restorable.

Create a uniquely named test bucket and object, retrieve it, compare a checksum, then remove only the test data. Confirm the object is visible from the intended Windows client path as well as the Linux-side client. A successful curl to the console proves only HTTP reachability; verify an actual S3 API operation through the SDK or command-line client your application will use.

If host-to-guest localhost forwarding is enabled in NAT mode, Microsoft documents that WSL 2 forwards ports from Linux to Windows localhost by default. Mirrored networking has a different behavior and ignores some forwarding settings. Confirm the active mode and access from Windows without assuming that every WSL setup uses NAT. Avoid changing .wslconfig and the MinIO bind address at the same time; isolate one variable per test.

Make restart and data ownership explicit

For repeatable local work, run the pinned lab build in a foreground terminal first. This makes logs and shutdown behavior visible. If you later create a systemd unit, define the Linux user, environment file, working directory, and data path explicitly. WSL supports systemd in recent WSL versions when enabled per distribution, but WSL shutdown still ends the VM and its services. A systemd service is not a promise of continuous availability while Windows sleeps or WSL is idle.

After a clean stop, restart the service and verify the same test object remains readable. Record the actual directory and server version. Do not test cleanup with rm -rf against an uncertain path; first use pwd, realpath, and a listing, then remove only a disposable test directory after the server is stopped.

Keep single-node semantics honest

MinIO’s archived project documentation distinguishes standalone single-node/single-drive use for local development or evaluation from deployments with more drives and failure tolerance. Multiple directories on one physical disk do not create independent hardware fault domains. WSL’s VHDX, Windows host storage, and physical device form additional shared failure layers. A Windows backup of the VHDX while the server is writing may not be application-consistent unless the process is stopped or a supported consistency procedure is used.

Do not evaluate production performance using /mnt/c and then attribute the bottleneck to MinIO. Benchmark the Linux filesystem path, CPU/memory limits, and host disk separately. Likewise, do not call an S3-compatible endpoint fully compatible with every AWS behavior; test the specific API operations, signing mode, multipart pattern, and SDK version your application needs.

Acceptance checks

A local development setup is ready when the server starts with a documented version and empty initial data path, binds only to the intended interfaces, answers a real object API request from Linux and the intended Windows client, preserves a test object across an orderly restart, and stops without orphaning the process. Keep test data and credentials clearly separated from production.

An isolated historical MinIO Community Server build in WSL can still help reproduce an application integration test, but its archived status makes it unsuitable as a default choice for a new maintained service. It is not a substitute for an actively supported object store, a designed multi-node deployment, independent backups, or a tested restore path.

Related:

Sources: