Visit a file (
Visit a file for viewing, without allowing changes to it
Visit a different file instead of the one visited last
Visit a file, in another window (
alter what is displayed in the selected window.
Visit a file, in a new frame (
alter what is displayed in the selected frame.
Visit a file with no conversion of the contents.
Visiting a file means reading its contents into an Emacs buffer so you can edit them. Emacs makes a new buffer for each file that you visit.
To visit a file, type C-x C-f (
find-file) and use the
minibuffer to enter the name of the desired file. While in the
minibuffer, you can abort the command by typing C-g. See File Names, for details about entering file names into minibuffers.
If the specified file exists but the system does not allow you to read it, an error message is displayed in the echo area (on GNU and Unix systems you might be able to visit such a file using the ‘su’ or ‘sudo’ methods; see Remote Files). Otherwise, you can tell that C-x C-f has completed successfully by the appearance of new text on the screen, and by the buffer name shown in the mode line (see The Mode Line). Emacs normally constructs the buffer name from the file name, omitting the directory name. For example, a file named /usr/rms/emacs.tex is visited in a buffer named ‘emacs.tex’. If there is already a buffer with that name, Emacs constructs a unique name; the normal method is to add a suffix based on the directory name (e.g., ‘<rms>’, ‘<tmp>’, and so on), but you can select other methods. See Making Buffer Names Unique.
To create a new file, just visit it using the same command, C-x C-f. Emacs displays ‘(New file)’ in the echo area, but in other respects behaves as if you had visited an existing empty file.
After visiting a file, the changes you make with editing commands are made in the Emacs buffer. They do not take effect in the visited file, until you save the buffer (see Saving Files). If a buffer contains changes that have not been saved, we say the buffer is modified. This implies that some changes will be lost if the buffer is not saved. The mode line displays two stars near the left margin to indicate that the buffer is modified.
If you visit a file that is already in Emacs, C-x C-f switches to the existing buffer instead of making another copy. Before doing so, it checks whether the file has changed since you last visited or saved it. If the file has changed, Emacs offers to reread it.
If you try to visit a file larger than
large-file-warning-threshold (the default is 10000000, which is
about 10 megabytes), Emacs asks you for confirmation first. You can
answer y to proceed with visiting the file or l to visit
the file literally (see below). Visiting large files literally speeds
up navigation and editing of such files, because various
potentially-expensive features are turned off. Note, however, that
Emacs cannot visit files that are larger than the maximum Emacs buffer
size, which is limited by the amount of memory Emacs can allocate and
by the integers that Emacs can represent (see Using Multiple Buffers). If you
try, Emacs displays an error message saying that the maximum buffer
size has been exceeded.
If you try to visit a file whose major mode (see Major Modes)
uses the tree-sitter parsing library, Emacs will display a warning if
the file’s size in bytes is larger than the value of the variable
treesit-max-buffer-size. The default value is 40 megabytes for
64-bit Emacs and 15 megabytes for 32-bit Emacs. This avoids the
danger of having Emacs run out of memory by preventing the activation
of major modes based on tree-sitter in such large buffers, because a
typical tree-sitter parser needs about 10 times as much memory as the
text it parses.
If the file name you specify contains shell-style wildcard
characters, Emacs visits all the files that match it. (On
case-insensitive filesystems, Emacs matches the wildcards disregarding
the letter case.) Wildcards include ‘?’, ‘*’, and
‘[…]’ sequences. To enter the wild card ‘?’ in a file
name in the minibuffer, you need to type C-q ?. See Quoted File Names, for information on how to visit a file whose name
actually contains wildcard characters. You can disable the wildcard
feature by customizing
If you’re asking to visit a file that’s already visited in a buffer,
but the file has changed externally, Emacs normally asks you whether
you want to re-read the file from disk. But if you set
nil, Emacs won’t query you,
but will instead just display the buffer’s contents before the
changes, and show an echo-area message telling you how to revert the
buffer from the file.
If you visit the wrong file unintentionally by typing its name
incorrectly, type C-x C-v (
find-alternate-file) to visit
the file you really wanted. C-x C-v is similar to C-x
C-f, but it kills the current buffer (after first offering to save it
if it is modified). When C-x C-v reads the file name to visit,
it inserts the entire default file name in the buffer, with point just
after the directory part; this is convenient if you made a slight
error in typing the name.
If you visit a file that is actually a directory, Emacs invokes
Dired, the Emacs directory browser. See Dired, the Directory Editor. You can disable
this behavior by setting the variable
nil; in that case, it is an error to try to visit a directory.
Files which are actually collections of other files, or file archives, are visited in special modes which invoke a Dired-like environment to allow operations on archive members. See File Archives, for more about these features.
If you visit a file that the operating system won’t let you modify,
or that is marked read-only, Emacs makes the buffer read-only too, so
that you won’t go ahead and make changes that you’ll have trouble
saving afterward. You can make the buffer writable with C-x C-q
read-only-mode). See Miscellaneous Buffer Operations.
If you want to visit a file as read-only in order to protect
yourself from entering changes accidentally, visit it with the command
C-x C-r (
find-file-read-only) instead of C-x C-f.
C-x 4 f (
find-file-other-window) is like C-x C-f
except that the buffer containing the specified file is selected in another
window. The window that was selected before C-x 4 f continues to
show the same buffer it was already showing. If this command is used when
only one window is being displayed, that window is split in two, with one
window showing the same buffer as before, and the other one showing the
newly requested file. See Multiple Windows.
C-x 5 f (
find-file-other-frame) is similar, but opens a
new frame, or selects any existing frame showing the specified file.
See Frames and Graphical Displays.
On graphical displays, there are two additional methods for visiting files. Firstly, when Emacs is built with a suitable GUI toolkit, commands invoked with the mouse (by clicking on the menu bar or tool bar) use the toolkit’s standard file selection dialog instead of prompting for the file name in the minibuffer. On GNU/Linux and Unix platforms, Emacs does this when built with GTK+, LessTif, and Motif toolkits; on MS-Windows and Mac, the GUI version does that by default. For information on how to customize this, see Using Dialog Boxes.
Secondly, Emacs supports drag and drop: dropping a file into an ordinary Emacs window visits the file using that window. As an exception, dropping a file into a window displaying a Dired buffer moves or copies the file into the displayed directory. For details, see Drag and Drop, and Other Dired Features.
On text-mode terminals and on graphical displays when Emacs was built without a GUI toolkit, you can visit files via the menu-bar ‘File’ menu, which has the ‘Visit New File’ and the ‘Open File’ items.
Each time you visit a file, Emacs automatically scans its contents to detect what character encoding and end-of-line convention it uses, and converts these to Emacs’s internal encoding and end-of-line convention within the buffer. When you save the buffer, Emacs performs the inverse conversion, writing the file to disk with its original encoding and end-of-line convention. See Coding Systems.
If you wish to edit a file as a sequence of ASCII
characters with no special encoding or conversion, use the M-x
find-file-literally command. This visits a file, like C-x C-f,
but does not do format conversion (see Format
Conversion in the Emacs Lisp Reference Manual), character code
conversion (see Coding Systems), or automatic uncompression
(see Accessing Compressed Files), and does not add a final newline because
require-final-newline (see Customizing Saving of Files). If you have
already visited the same file in the usual (non-literal) manner, this
command asks you whether to visit it literally instead.
Files are sometimes (loosely) tied to other files, and you could call
these files sibling files. For instance, when editing C files,
if you have a file called ‘"foo.c"’, you often also have a file
called ‘"foo.h"’, and that could be its sibling file. Or you may
have different versions of a file, for instance
‘"src/emacs/emacs-28/lisp/allout.el"’ might be considered
siblings. Emacs provides the
find-sibling-file command to jump
between sibling files, but it’s impossible to guess at which files a
user might want to be considered siblings, so Emacs lets you configure
this freely by altering the
find-sibling-rules user option.
This is a list of match/expansion elements.
For instance, to do the ‘".c"’ to ‘".h"’ mapping, you could say:
(setq find-sibling-rules '(("\\([^/]+\\)\\.c\\'" "\\1.h")))
ff-find-related-file offers similar functionality especially
geared towards C files, see Other Commands for C Mode.)
Or, if you want to consider all files under ‘"src/emacs/DIR/file-name"’ to be siblings of other dirs, you could say:
(setq find-sibling-rules '(("src/emacs/[^/]+/\\(.*\\)\\'" "src/emacs/.*/\\1")))
As you can see, this is a list of (MATCH EXPANSION...) elements. The match is a regular expression that matches the visited file name, and each expansion may refer to match groups by using ‘\\1’ and so on. The resulting expansion string is then applied to the file system to see if any files match this expansion (interpreted as a regexp).
Two special hook variables allow extensions to modify the operation
of visiting files. Visiting a file that does not exist runs the
find-file-not-found-functions; this variable holds
a list of functions, which are called one by one (with no arguments)
until one of them returns non-
nil. This is not a normal hook,
and the name ends in ‘-functions’ rather than ‘-hook’ to
indicate that fact.
Successful visiting of any file, whether existing or not, calls the
find-file-hook, with no arguments. This variable
is a normal hook. In the case of a nonexistent file, the
find-file-not-found-functions are run first. See Hooks.