Jimfs: an in-memory java.nio.file file system for tests

What Jimfs replaces, and for whom

Code that walks directories, resolves relative paths or writes temp files is awkward to test. The usual workarounds are JUnit's TemporaryFolder, a temp directory under /tmp, or mocking the file system APIs. The first two leave state behind and can collide when tests run in parallel; the third means hand-writing a fake for an interface with hundreds of methods.

Jimfs takes a different route. It is a complete implementation of the java.nio.file abstract file system APIs that stores everything in the JVM heap. Tests get a real FileSystem object, real Path objects, real Files calls, and nothing survives the process. The README describes it as "an in-memory file system for Java 8 and above", so the target reader is a Java developer writing tests for code that already speaks Path and Files rather than java.io.File.

The audience is narrow on purpose. If your production code opens files through java.io.File, or through a library that resolves paths itself, swapping in a Jimfs instance is not possible without changing that code. Jimfs is a test-time substitute for the file system, not a runtime dependency you ship.

How the java.nio.file provider is wired

Jimfs plugs into the JDK's file system provider mechanism. Configuration objects describe the flavour of the file system: paths, separators and behaviour modelled on Unix or on Windows. Jimfs.newFileSystem(Configuration.unix()) returns a FileSystem whose provider is Jimfs's own, so every Path you obtain from it carries that provider and every Files operation routes back into Jimfs rather than the default provider.

Because the file system is a provider rather than a wrapper, the operations are the ordinary ones. The README lists creating, deleting, moving and copying files and directories; reading and writing through FileChannel, SeekableByteChannel, InputStream and OutputStream; symbolic links; hard links to regular files; SecureDirectoryStream for operations relative to an open directory; glob and regex filtering with PathMatcher; a WatchService for directory changes; and file attributes across the basic, owner, posix, unix, dos, acl and user views.

Two details in that list matter more than the rest. SecureDirectoryStream and WatchService are the parts of java.nio.file that most fake file systems skip, and their presence is what lets Jimfs stand in for code that opens directories and registers watchers. The attribute views are the opposite case: the README states that not all views provide useful attributes, and gives the example that POSIX permissions can be set and read with the posix view but "will not actually affect the behavior of the file system". A test that asserts a write fails on a read-only file will pass or fail for the wrong reason.

Installing Jimfs and creating a file

Jimfs is published on Maven Central as com.google.jimfs:jimfs:1.3.2, which the README identifies as the latest release. Add it to your build as a test-scoped dependency. The README gives this Maven snippet:

<dependency>
  <groupId>com.google.jimfs</groupId>
  <artifactId>jimfs</artifactId>
  <version>1.3.2</version>
</dependency>

For a Gradle build the coordinates are the same, so the line reads testImplementation 'com.google.jimfs:jimfs:1.3.2'.

The basic use example from the README obtains a file system, creates a directory and writes a file into it:

import com.google.common.jimfs.Configuration;
import com.google.common.jimfs.Jimfs;

FileSystem fs = Jimfs.newFileSystem(Configuration.unix());
Path foo = fs.getPath("/foo");
Files.createDirectory(foo);

Path hello = foo.resolve("hello.txt"); // /foo/hello.txt
Files.write(hello, ImmutableList.of("hello world"), StandardCharsets.UTF_8);

After this runs, hello is a Path in the Jimfs instance and Files.readAllLines(hello) returns the single line. Nothing appears on disk. To convert a Jimfs Path into something a legacy API accepts, call hello.toFile(), which is the operation behind the common "jimfs path to file" search; note that the resulting File is only meaningful while that Jimfs instance is alive.

Cleanup is explicit. The FileSystem implements Closeable, so a try-with-resources block around Jimfs.newFileSystem(...) releases the instance at the end of the test and prevents one test's tree from leaking into the next.

Where Jimfs stops being the right tool

The README is direct that behaviour is modelled after UNIX and may not exactly match any particular real file system or platform. That gap is the main risk. A test that passes against Jimfs proves your path handling and directory logic are self-consistent; it does not prove the code works against ext4, APFS or NTFS, where case sensitivity, filename length limits, reserved names and locking differ.

Memory is the second boundary. Everything lives in the heap, so a test that writes a multi-gigabyte file, or thousands of small ones, will show up as GC pressure rather than as disk usage. There is no spill-to-disk path in the README.

Persistence is the third. The file system exists for the lifetime of the object; a new JVM starts empty. Anything that depends on state surviving a restart, or on two processes seeing the same tree, is outside what Jimfs offers. Memory-mapped files are not in the supported list either. And the permission caveat cuts the other way from convenience: if your code branches on PosixFilePermissions, Jimfs will let you set them and read them back, but it will not enforce them, so the branch you are trying to test is not the branch you are exercising.

Jimfs against a temp directory and against in-memory VFS libraries

The closest alternative is not another library but the JDK itself: create a temp directory with Files.createTempDirectory and use the default file system. That approach exercises the real provider, so permissions, locking and case behaviour are genuine, and it needs no dependency. The costs are that it touches disk, that cleanup is your responsibility, and that parallel tests must be given distinct roots or they interfere.

Jimfs trades that realism for isolation and speed of setup. Each test gets a fresh FileSystem from a one-line call, no path collisions are possible between tests, and nothing needs deleting afterwards. The trade is that you are testing against a model of a file system rather than a file system. A useful split is to run the same test body twice: once against Jimfs for the fast inner loop, and once against a temp directory in a slower integration pass that catches provider-specific behaviour.

Libraries that present an in-memory VFS usually define their own abstraction over paths and streams rather than implementing java.nio.file. That means production code must be written against the library's types. Jimfs's distinguishing choice is the opposite: it implements the JDK interfaces, so production code stays unchanged and only the test swaps the FileSystem instance.

Maintenance, upgrade cost and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-24. Releases are infrequent: v1.3.0 in July 2023, v1.3.1 in July 2025, and v1.3.2 in August 2026. That cadence is consistent with a small, stable surface: the java.nio.file API it implements changes slowly, so there is little to keep up with. The practical upgrade cost is low, but so is the chance of a quick fix if you hit a behaviour mismatch, since there is no fast release train behind it.

Jimfs is licensed under Apache-2.0, and the README carries the full Apache License 2.0 text with the copyright line "Copyright 2013 Google Inc." Apache-2.0 permits commercial and closed-source use and includes a patent grant, but it also requires that you retain the licence and notice files for redistributed code. Because Jimfs is normally a test-scoped dependency, it usually does not end up in a shipped artifact at all, which keeps the notice obligation contained to your build. Whether that applies to your distribution is a question for your own legal review, not something the README answers.

Editorial conclusion

Adopt Jimfs when your code takes a Path or FileSystem and your tests need real directory trees without touching disk; skip it when you need POSIX permission enforcement, mmap, or persistence across a JVM restart. Before wiring it in, verify that the attribute views your code reads are the ones Jimfs actually populates, since the README warns that some views return attributes that do not affect behaviour.

Frequently asked questions

Official sources

1. google/jimfs on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases