Path Utilities (bpy.path)

This module has a similar scope to os.path, containing utility functions for dealing with paths in Blender.

bpy.path.abspath(path, *, start=None, library=None)

Returns the absolute path relative to the current blend file using the “//” prefix.

Parameters:
  • start (string or bytes) – Relative to this path, when not set the current filename is used.

  • library (bpy.types.Library) – The library this path is from. This is only included for convenience, when the library is not None its path replaces start.

Returns:

The absolute path.

Return type:

string

bpy.path.basename(path)

Equivalent to os.path.basename, but skips a “//” prefix.

Use for Windows compatibility.

Returns:

The base name of the given path.

Return type:

string

bpy.path.clean_name(name, *, replace='_')

Returns a name with characters replaced that may cause problems under various circumstances, such as writing to a file.

All characters besides A-Z/a-z, 0-9 are replaced with “_” or the replace argument if defined.

Parameters:
  • name (string or bytes) – The path name.

  • replace (string) – The replacement for non-valid characters.

Returns:

The cleaned name.

Return type:

string

bpy.path.display_name(name, *, has_ext=True, title_case=True)

Creates a display string from name to be used menus and the user interface. Intended for use with filenames and module names.

Parameters:
  • name (string) – The name to be used for displaying the user interface.

  • has_ext (boolean) – Remove file extension from name.

  • title_case (boolean) – Convert lowercase names to title case.

Returns:

The display string.

Return type:

string

bpy.path.display_name_to_filepath(name)

Performs the reverse of display_name using literal versions of characters which aren’t supported in a filepath.

Parameters:

name (string) – The display name to convert.

Returns:

The file path.

Return type:

string

bpy.path.display_name_from_filepath(name)

Returns the path stripped of directory and extension, ensured to be utf8 compatible.

Parameters:

name (string) – The file path to convert.

Returns:

The display name.

Return type:

string

bpy.path.ensure_ext(filepath, ext, *, case_sensitive=False)

Return the path with the extension added if it is not already set.

Parameters:
  • filepath (string) – The file path.

  • ext (string) – The extension to check for, can be a compound extension. Should start with a dot, such as ‘.blend’ or ‘.tar.gz’.

  • case_sensitive (boolean) – Check for matching case when comparing extensions.

Returns:

The file path with the given extension.

Return type:

string

bpy.path.is_subdir(path, directory)

Returns true if path in a subdirectory of directory. Both paths must be absolute.

Parameters:

path (string or bytes) – An absolute path.

Returns:

Whether or not the path is a subdirectory.

Return type:

boolean

bpy.path.module_names(path, *, recursive=False, package='')

Return a list of modules which can be imported from path.

Parameters:
  • path (string) – a directory to scan.

  • recursive (bool) – Also return submodule names for packages.

  • package (string) – Optional string, used as the prefix for module names (without the trailing “.”).

Returns:

a list of string pairs (module_name, module_file).

Return type:

list of strings

bpy.path.native_pathsep(path)

Replace the path separator with the systems native os.sep.

Parameters:

path (string) – The path to replace.

Returns:

The path with system native separators.

Return type:

string

bpy.path.reduce_dirs(dirs)

Given a sequence of directories, remove duplicates and any directories nested in one of the other paths. (Useful for recursive path searching).

Parameters:

dirs (sequence of strings) – Sequence of directory paths.

Returns:

A unique list of paths.

Return type:

list of strings

bpy.path.relpath(path, *, start=None)

Returns the path relative to the current blend file using the “//” prefix.

Parameters:
  • path (string or bytes) – An absolute path.

  • start (string or bytes) – Relative to this path, when not set the current filename is used.

Returns:

The relative path.

Return type:

string

bpy.path.resolve_ncase(path)

Resolve a case insensitive path on a case sensitive system, returning a string with the path if found else return the original path.

Parameters:

path (string) – The path name to resolve.

Returns:

The resolved path.

Return type:

string