ubelt.util_path module

Functions for working with filesystem paths.

The expandpath() function expands the tilde to $HOME and environment variables to their values.

The augpath() function creates variants of an existing path without having to spend multiple lines of code splitting it up and stitching it back together.

The shrinkuser() function replaces your home directory with a tilde.

The userhome() function reports the home directory of the current user of the operating system.

The ensuredir() function operates like mkdir -p in unix.

ubelt.util_path.augpath(path, suffix='', prefix='', ext=None, base=None, dpath=None, multidot=False)[source]

Create a new path with a different extension, basename, directory, prefix, and/or suffix.

A prefix is inserted before the basename. A suffix is inserted between the basename and the extension. The basename and extension can be replaced with a new one. Essentially a path is broken down into components (dpath, base, ext), and then recombined as (dpath, prefix, base, suffix, ext) after replacing any specified component.

  • path (str | PathLike) – a path to augment
  • suffix (str, default=’‘) – placed between the basename and extension
  • prefix (str, default=’‘) – placed in front of the basename
  • ext (str, default=None) – if specified, replaces the extension
  • base (str, default=None) – if specified, replaces the basename without extension
  • dpath (str | PathLike, default=None) – if specified, replaces the directory
  • multidot (bool, default=False) – Allows extensions to contain multiple dots. Specifically, if False, everything after the last dot in the basename is the extension. If True, everything after the first dot in the basename is the extension.

augmented path

Return type:



>>> import ubelt as ub
>>> path = 'foo.bar'
>>> suffix = '_suff'
>>> prefix = 'pref_'
>>> ext = '.baz'
>>> newpath = ub.augpath(path, suffix, prefix, ext=ext, base='bar')
>>> print('newpath = %s' % (newpath,))
newpath = pref_bar_suff.baz


>>> augpath('foo.bar')
>>> augpath('foo.bar', ext='.BAZ')
>>> augpath('foo.bar', suffix='_')
>>> augpath('foo.bar', prefix='_')
>>> augpath('foo.bar', base='baz')
>>> augpath('foo.tar.gz', ext='.zip', multidot=True)
>>> augpath('foo.tar.gz', ext='.zip', multidot=False)
>>> augpath('foo.tar.gz', suffix='_new', multidot=True)

Returns the path to some user’s home directory.


username (str, default=None) – name of a user on the system. If not specified, the current user is inferred.


userhome_dpath: path to the specified home directory

Return type:


  • KeyError – if the specified user does not exist on the system
  • OSError – if username is unspecified and the current user cannot be inferred


>>> import getpass
>>> username = getpass.getuser()
>>> assert userhome() == expanduser('~')
>>> assert userhome(username) == expanduser('~')
ubelt.util_path.shrinkuser(path, home='~')[source]

Inverse of os.path.expanduser().

  • path (str | PathLike) – path in system file structure
  • home (str, default=’~’) – symbol used to replace the home path. Defaults to ‘~’, but you might want to use ‘$HOME’ or ‘%USERPROFILE%’ instead.

path: shortened path replacing the home directory with a tilde

Return type:



>>> path = expanduser('~')
>>> assert path != '~'
>>> assert shrinkuser(path) == '~'
>>> assert shrinkuser(path + '1') == path + '1'
>>> assert shrinkuser(path + '/1') == join('~', '1')
>>> assert shrinkuser(path + '/1', '$HOME') == join('$HOME', '1')
>>> assert shrinkuser('.') == '.'

Shell-like environment variable and tilde path expansion.

Less aggressive than truepath. Only expands environs and tilde. Does not change relative paths to absolute paths.

Parameters:path (str | PathLike) – string representation of a path
Returns:expanded path
Return type:str


>>> import ubelt as ub
>>> assert normpath(ub.expandpath('~/foo')) == join(ub.userhome(), 'foo')
>>> assert ub.expandpath('foo') == 'foo'
ubelt.util_path.ensuredir(dpath, mode=1023, verbose=None, recreate=False)[source]

Ensures that directory will exist. Creates new dir with sticky bits by default

  • dpath (str | PathLike | Tuple[str | PathLike]) – dir to ensure. Can also be a tuple to send to join
  • mode (int, default=0o1777) – octal mode of directory
  • verbose (int, default=0) – verbosity
  • recreate (bool, default=False) – if True removes the directory and all of its contents and creates a fresh new directory. USE CAREFULLY.

path: the ensured directory

Return type:



This function is not thread-safe in Python2


>>> from ubelt.util_platform import *  # NOQA
>>> import ubelt as ub
>>> cache_dpath = ub.ensure_app_cache_dir('ubelt')
>>> dpath = join(cache_dpath, 'ensuredir')
>>> if exists(dpath):
...     os.rmdir(dpath)
>>> assert not exists(dpath)
>>> ub.ensuredir(dpath)
>>> assert exists(dpath)
>>> os.rmdir(dpath)
class ubelt.util_path.TempDir[source]

Bases: object

Context for creating and cleaning up temporary directories.


>>> with TempDir() as self:
>>>     dpath = self.dpath
>>>     assert exists(dpath)
>>> assert not exists(dpath)


>>> self = TempDir()
>>> dpath = self.ensure()
>>> assert exists(dpath)
>>> self.cleanup()
>>> assert not exists(dpath)