Convert file paths to canonical form for the platform, to display them in a user-understandable form and so that relative and absolute paths can be compared.




character vector of file paths.


A character vector.

If an input is not a real path the result is system-dependent (unless mustWork = TRUE, when this should be an error). It will be either the corresponding input element or a transformation of it into an absolute path.

Converting to an absolute file path can fail for a large number of reasons. The most common are

  • One of more components of the file path does not exist.

  • A component before the last is not a directory, or there is insufficient permission to read the directory.

  • For a relative path, the current directory cannot be determined.

  • A symbolic link points to a non-existent place or links form a loop.

  • The canonicalized path would be exceed the maximum supported length of a file path.


Tilde-expansion (see path.expand) is first done on paths.

Where the Unix-alike platform supports it attempts to turn paths into absolute paths in their canonical form (no ./, ../ nor symbolic links). It relies on the POSIX system function realpath: if the platform does not have that (we know of no current example) then the result will be an absolute path but might not be canonical. Even where realpath is used the canonical path need not be unique, for example via hard links or multiple mounts.

On Windows it converts relative paths to absolute paths, resolves symbolic links, converts short names for path elements to long names and ensures the separator is that specified by winslash. It will match each path element case-insensitively or case-sensitively as during the usual name lookup and return the canonical case. It relies on Windows API function GetFinalPathNameByHandle and in case of an error (such as insufficient permissions) it currently falls back to the R 3.6 (and older) implementation, which relies on GetFullPathName and GetLongPathName with limitations described in the Notes section. An attempt is made not to introduce UNC paths in presence of mapped drives or symbolic links: if GetFinalPathNameByHandle returns a UNC path, but GetLongPathName returns a path starting with a drive letter, R falls back to the R 3.6 (and older) implementation. UTF-8-encoded paths not valid in the current locale can be used.

mustWork = FALSE is useful for expressing paths for use in messages.


Updated 2019-10-22.

See also

Standard path modifiers:

Checking for existence, access:


#> [1] "/Users/mike/git/monorepo/r-packages/acidbase/docs/reference"
#> [1] "/Users/mike/git/monorepo/r-packages/acidbase/docs/reference"