filepath: Library for manipulating FilePaths in a cross platform way.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

This package provides functionality for manipulating FilePath values, and is shipped with GHC. It provides two variants for filepaths:

  1. legacy filepaths: type FilePath = String

  2. abstract filepaths: internally unpinned ShortByteString (platform-dependent encoding)

It is recommended to use AbstractFilePath when possible, because it is more correct.

For each variant there are three main modules:

System.OsString is like System.AbstractFilePath, but more general purpose. Refer to the documentation of those modules for more information.

[Skip to Readme]


Versions 1.0,,,,,,,,,,,,,,, 1.4.2,,,,,,,,,,, 1.4.300.1, 1.4.300.2,,,,
Change log
Dependencies base (>=4.9 && <4.18), bytestring (>=, deepseq, exceptions, template-haskell [details]
License BSD-3-Clause
Copyright Neil Mitchell 2005-2020
Author Neil Mitchell <>
Maintainer Julian Ospald <>
Category System
Home page
Bug tracker
Source repo head: git clone
Uploaded by maerwald at 2022-06-18T23:11:45Z


[Index] [Quick Jump]


Manual Flags


Use cpphs (fixes haddock source links)


Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for filepath-

[back to package description]

FilePath Hackage version

The filepath package provides functionality for manipulating FilePath values, and is shipped with GHC. It provides three modules:

All three modules provide the same API, and the same documentation (calling out differences in the different variants).

What is a FilePath?

In Haskell, the legacy definition (used in base and Prelude) is type FilePath = String, where a Haskell String is a list of Unicode code points.

The new definition is (simplified) newtype AbstractFilePath = AFP ShortByteString, where ShortByteString is an unpinned byte array and follows syscall conventions, preserving the encoding.

On unix, filenames don't have a predefined encoding as per the POSIX specification and are passed as char[] to syscalls.

On windows (at least the API used by Win32) filepaths are UTF-16 strings.

You are encouraged to use AbstractFilePath whenever possible, because it is more correct.

Also note that this is a low-level library and it makes no attempt at providing a more type safe variant for filepaths (e.g. by distinguishing between absolute and relative paths) and ensures no invariants (such as filepath validity).

For such libraries, check out the following: