Skip to main content

A module wrapper for os.path

Project description implements a path objects as first-class entities, allowing common operations on files to be invoked on those path objects directly. For example:

from path import Path
d = Path('/home/guido/bin')
for f in d.files('*.py'):
    f.chmod(0755) is hosted at Github.

Documentation is hosted with PyPI.

Guides and Testimonials

Yasoob has written the Python 101 Writing a Cleanup Script based on

Installing may be installed using setuptools, distribute, or pip:

pip install

The latest release is always updated to the Python Package Index.

You may also always download the source distribution (zip/tarball), extract it, and run python to install it.


To install an in-development version, use the Github links to clone or download a snapshot of the latest code. Alternatively, if you have git installed, you may be able to use pip or easy_install to install directly from the repository:

pip install git+


Tests are continuously run by Travis-CI: BuildStatus

To run the tests, refer to the .travis.yml file for the steps run on the Travis-CI hosts.



  • #93: chown now appears in docs and raises NotImplementedError if os.chown isn’t present.
  • #92: Added compatibility support for .samefile on platforms without os.samefile.


  • #91: Releases now include a universal wheel.


  • In chmod, added support for multiple symbolic masks (separated by commas).
  • In chmod, fixed issue in setting of symbolic mask with ‘=’ where unreferenced permissions were cleared.


  • #23: Added support for symbolic masks to .chmod.


  • The open method now uses and supports all of the parameters to that function. open will always raise an OSError on failure, even on Python 2.
  • Updated write_text to support additional newline patterns.
  • The text method now always returns text (never bytes), and thus requires an encoding parameter be supplied if the default encoding is not sufficient to decode the content of the file.


  • path class renamed to Path. The path name remains as an alias for compatibility.


  • chown now accepts names in addition to numeric IDs.


  • Drop support for Python 2.5. Python 2.6 or later required.
  • Installation now requires setuptools.


  • Allow arbitrary callables to be passed to path.walk errors parameter. Enables workaround for issues such as #73 and #56.


  • #61: path.listdir now decodes filenames from os.listdir when loading characters from a file. On Python 3, the behavior is unchanged. On Python 2, the behavior will now mimick that of Python 3, attempting to decode all filenames and paths using the encoding indicated by sys.getfilesystemencoding(), and escaping any undecodable characters using the ‘surrogateescape’ handler.


  • #53: Added path.in_place for editing files in place.


  • path.fnmatch now takes an optional parameter normcase and this parameter defaults to self.module.normcase (using case normalization most pertinent to the path object itself). Note that this change means that any paths using a custom ntpath module on non-Windows systems will have different fnmatch behavior. Before:

    # on Unix
    >>> p = path('Foo')
    >>> p.module = ntpath
    >>> p.fnmatch('foo')


    # on any OS
    >>> p = path('Foo')
    >>> p.module = ntpath
    >>> p.fnmatch('foo')

    To maintain the original behavior, either don’t define the ‘module’ for the path or supply explicit normcase function:

    >>> p.fnmatch('foo', normcase=os.path.normcase)
    # result always varies based on OS, same as fnmatch.fnmatch

    For most use-cases, the default behavior should remain the same.

  • Issue #50: Methods that accept patterns (listdir, files, dirs, walk, walkdirs, walkfiles, and fnmatch) will now use a normcase attribute if it is present on the pattern parameter. The path module now provides a CaseInsensitivePattern wrapper for strings suitable for creating case-insensitive patterns for those methods.


  • Issue #44: _hash method would open files in text mode, producing invalid results on Windows. Now files are opened in binary mode, producing consistent results.
  • Issue #47: Documentation is dramatically improved with Intersphinx links to the Python os.path functions and documentation for all methods and properties.


  • Issue #32: Add chdir and cd methods.


  • open() now passes all positional and keyword arguments through to the underlying call.


  • Native Python 2 and Python 3 support without using 2to3 during the build process.


  • Added a chunks() method to a allow quick iteration over pieces of a file at a given path.
  • Issue #28: Fix missing argument to samefile.
  • Initializer no longer enforces isinstance basestring for the source object. Now any object that supplies __unicode__ can be used by a path (except None). Clients that depend on a ValueError being raised for int and other non-string objects should trap these types internally.
  • Issue #30: chown no longer requires both uid and gid to be provided and will not mutate the ownership if nothing is provided.


  • Issue #22: __enter__ now returns self.


  • Issue #20: relpath now supports a “start” parameter to match the signature of os.path.relpath.


  • Minimum Python version is now 2.5.


  • Issue #5: Implemented path.tempdir, which returns a path object which is a temporary directory and context manager for cleaning up the directory.

  • Issue #12: One can now construct path objects from a list of strings by simply using path.joinpath. For example:

    path.joinpath('a', 'b', 'c') # or


  • Issue #7: Add the ability to do chaining of operations that formerly only returned None.
  • Issue #4: Raise a TypeError when constructed from None.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for, version 7.4
Filename, size File type Python version Upload date Hashes
Filename, size (27.3 kB) File type Source Python version None Upload date Hashes View
Filename, size (29.5 kB) File type Wheel Python version 3.4 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page