Idea Plugin Dev - File and File System (Virtual)

Card Puncher Data Processing


A virtual file com.intellij.openapi.vfs.VirtualFile is the Idea’s representation of a file in a file system (a Virtual File System).


File System (VFS)

Virtual file system implementation

Most commonly, a virtual file is a file in your local file system. However, the IntelliJ Platform supports multiple pluggable file system implementations, so virtual files can also represent:

  • classes in a JAR file,
  • old revisions of files loaded from a version control repository,
  • and so on.

To provide an alternative file system implementation (for example, an FTP file system):

  • implement the VirtualFileSystem class
  • implement the VirtualFile
  • register your implementation as an application component.

Build / Refresh

The VFS is built incrementally, by scanning the 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.getInstance().refresh()
  • or VirtualFile.refresh().

VFS refreshes are also triggered whenever file system watchers receive file system change notifications (available on the Windows and Mac operating systems).

As a plugin developer, you may want to invoke a VFS refresh if you need to access a file that has just been created by an external tool through the IntelliJ Platform APIs.


A particular file on disk is represented by equal VirtualFile instances for the entire lifetime of the IDEA process. There may be several instances corresponding to the same file, and they can be garbage-collected. The file is a UserDataHolder, and the user data is shared between those equal instances. If a file is deleted, its corresponding VirtualFile instance becomes invalid (the isValid() method returns false and operations cause exceptions).

Extension Point

To hook into operations performed in the local file system (for example, if you are developing a version control system integration that needs custom rename/move handling):

  • implement the LocalFileOperationsHandler interface
  • register it through the LocalFileSystem.registerAuxiliaryFileOperationsHandler method.

Change Notification

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

Directory Tree

Recursive Operations

Recursive iteration should be performed using VfsUtilCore.iterateChildrenRecursively to prevent endless loops caused by recursive symlinks.



The VFS level deals only with binary content. You can get or set the contents of a VirtualFile as a stream of bytes, but concepts like encodings and line separators are handled on higher system levels.

See document which typically corresponds to the text contents of a virtual file.


To get a file:

  • From an action: e.getData(PlatformDataKeys.VIRTUAL_FILE). If you are interested in multiple selection, you can also use 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()


Without VFS / External Tool

Usually you don’t create a file through VFS. As a rule, files are created either:

As a plugin developer, you may want to invoke a VFS refresh if you need to access a file that has just been created by an external tool through the IntelliJ Platform APIs.

Through VFS

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 the file.


A file has an application scope (even if multiple projects are open, each file is represented by the same VirtualFile instance).

Documentation / Reference

Discover More
Card Puncher Data Processing
IDEA Plugin Dev - File View Providers (Multiple PSI Tree in one file)

A file view provider (see the com/intellij/psi/FileViewProviderFileViewProvider class) manage access to multiple PSI trees within a single file. For example, a JSPX page has: a separate PSI tree for...
Card Puncher Data Processing
IDEA Plugin Dev - Module ( API )

Working with Modules in a plugin API The IntelliJ Platform provides a number of Java classes and interfaces you can use to work with modules within the project and core API Class Class Type API...
Card Puncher Data Processing
IDEA Plugin Dev - PSI Element

A PSI element is an element of a PSI tree. It can have child PSI elements. PSI elements and operations on the level of individual PSI elements are used to explore the internal structure of source code....
Idea Project Model Dev
IDEA Plugin Dev - Project

from a plugin dev point of view A project consists of one or several modules. Each module includes the plugin source code Each module includes order entries that refer to SDK and libraries...
Card Puncher Data Processing
Idea - Plugin Development

How to develop IDEA plugin. The most common types of plugins include: Custom language support (File type recognition, Lexical analysis, Syntax highlighting, Formatting, Code insight and code completion,...
Card Puncher Data Processing
Idea Plugin Dev - Documents

A document is an editable sequence of Unicode characters, which typically corresponds to the text contents of a virtual file. Line breaks in a document are always normalized to \n. The IntelliJ...
Card Puncher Data Processing
Idea Plugin Dev - File Type Definition

A file must be associated to a file type. In plugin.xml, via platform extension Run the project, create a file with the same extension and verify that this the good Icon See registering...
Card Puncher Data Processing
Idea Plugin dev - PSI File (Program Structure Interface - Tree Structured Content)

A PSI (Program Structure Interface) file is the root of a structure representing the contents of a file as a hierarchy of elements in a particular programming language. It represents a hierarchy of PSI...

Share this page:
Follow us:
Task Runner