Child pages
  • IntelliJ IDEA Architectural Overview

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Virtual Files

A virtual file (com.intellij.openapi.vfs.VirtualFile ) is IntelliJ IDEA's representation of a file in a filesystem file system (VFS). The most common case of a virtual file is a file on your local filesystemfile system. However, IDEA supports multiple pluggable filesystem file system implementations, so virtual files can also represent classes in a JAR file, old revisions of files loaded from the CVS repository and so on.


  • From an action: e.getData(PlatformDataKeys.VIRTUAL_FILE). If you are interested in multiple selection, you can also query fileuery for e.getData(PlatformDataKeys.VIRTUAL_FILE_ARRAY).
  • From a path in the local file system: LocalFileSystem.getInstance().findFileByIoFile()
  • From a PSI file: psiFile.getVirtualFile() (may return null if the PSI file exists only in memory)
  • From a document: FileDocumentManager.getInstance().getFile()


The VFS is built incrementally, by walking scanning the filesystem file system up and down starting from the project root. New files appearing in the file system are detected by VFS refreshes. A refresh operation can be initiated programmatically using (VirtualFileManager.refresh() or VirtualFile.refresh()). VFS refreshes are also caused by the file system change notifications received by file system watchers (on Windows and Mac).

As a plugin developer, you may need to invoke a VFS refresh if you need to access through IDEA's APIs a file which that has just been created by an external tool through IDEA's APIs.

How long does it live?

A particular file on disk is represented by the same VirtualFile instance for the entire lifetime of the IDEA process. If a file is deleted, its corresponding VirtualFile instance becomes invalid ( the isValid() method returns false and operations cause exceptions).

How do I create one?

Usually you don't: as a rule, files are created either through the PSI API or through the regular API. If you do need to create a file through VFS, you can use the VirtualFile.createChildData() method to create a VirtualFile instance and the VirtualFile.setBinaryContent() method to write some data to itthe file.

How do I get notified when it changes?

The VirtualFileManager.addVirtualFileListener() method allows you to receive notifications about all changes happening in the VFS.

How do I extend it?

To provide an alternative filesystem file system implementation (for example, an FTP filesystemfile system), implement the VirtualFileSystem interface (most likely you'll also need to implement VirtualFile), and register your implementation as an application component . To hook into operations performed in the local file system (for example, if you 're developing deal with development of a version control system integration which that needs custom rename/move handling), implement the LocalFileOperationsHandler interface and register it through the LocalFileSystem.registerAuxiliaryFileOperationsHandler method.

What are the rules for working with it?