Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Strings and I/O

C++ std::filesystem library

Reference for C++17 std::filesystem: the path class, splitting and joining paths, querying files, error handling with exceptions or error_code, and portability.

<filesystem> (C++17) is the standard library for working with files and directories as objects of the file system rather than streams of bytes. It has two halves. The class std::filesystem::path is a value type that represents a path and takes it apart or puts it together without touching the disk. A set of free functions (exists, file_size, create_directories, remove, copy and more) then ask the operating system to look at or change real files.

Everything lives in namespace std::filesystem, which is almost always shortened with namespace fs = std::filesystem;. This page covers paths and queries. Changing the file system (copying, renaming, deleting, listing directories) is on Filesystem operations.

C++
#include <filesystem>
namespace fs = std::filesystem;

fs::path p = "reports/2025/summary.txt";
std::cout << p.filename() << " " << p.extension() << "\n";

Try it

C++ Taking paths apart and putting them together

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ Asking the file system questions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
namespace fs = std::filesystem;

class fs::path;                                   // value type, no disk access
bool        fs::exists(const path& p);
bool        fs::exists(const path& p, std::error_code& ec) noexcept;
uintmax_t   fs::file_size(const path& p);
path        fs::temp_directory_path();
path        fs::current_path();
path        fs::absolute(const path& p);
path        fs::canonical(const path& p);         // must exist; resolves . .. and links
Path member Description
filename(), stem(), extension() Last component, last component without its extension, and the extension including the dot.
parent_path(), root_path() Everything before the last component, and the root (/ on POSIX, C:\ on Windows).
has_filename(), is_absolute(), is_relative() Simple predicates on the path text.
operator/, /= Join with a directory separator. An absolute right operand replaces the left one.
operator+=, concat Append text with no separator.
replace_extension(), replace_filename(), remove_filename() Modify in place.
lexically_normal(), lexically_relative(base) Text-only clean-up and relative-path computation.
string(), generic_string(), u8string() Convert to a string in the native, portable (/) or UTF-8 form.

Returns / errors: each query function has two overloads. The plain one throws std::filesystem::filesystem_error (derived from std::system_error) on failure. The overload with a trailing std::error_code& never throws; it sets ec and returns a failure value (for file_size, the maximum uintmax_t, as the run above shows).

Usage notes

  • A path is just text. Creating one does not check that the file exists, and the name need not be valid. exists, status and similar functions are what consult the disk.
  • Native versus generic format. On Windows the native separator is \ and path::value_type is wchar_t; on POSIX it is / and char. Use generic_string() when you need the same text on every platform, and u8string() for UTF-8.
  • Streaming a path with << prints it quoted ("a/b.txt"). Call .string() when you want the bare text.
  • stem() and extension() split at the last dot of the filename only: archive.tar.gz has stem archive.tar and extension .gz. A name like .bashrc has no extension.
  • / replaces on absolute operands. path("a") / "/b" is /b, not a/b. This surprises people who join user input to a base directory; validate user-supplied names first.
  • Race conditions are inherent. Between exists(p) and the next call another process can change the file. Prefer to just attempt the operation and handle the error.
  • Time-of-check issues and symlinks. canonical and weakly_canonical resolve links; lexically_normal does not and can be wrong when .. follows a symlink.
  • Portability. The library needs C++17. On older GCC releases (before 9) you had to link -lstdc++fs. Filesystem access can be unavailable or restricted in sandboxes, containers and some embedded targets.