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 (str | 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:

str

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:: str

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 (str | bytes) – The path name.
replace (str) – The replacement for non-valid characters.

Returns:

The cleaned name.

Return type:

str

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 (str) – The name to be used for displaying the user interface.
has_ext (bool) – Remove file extension from name.
title_case (bool) – Convert lowercase names to title case.

Returns:

The display string.

Return type:

str

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 (str) – The display name to convert.
Returns:: The file path.
Return type:: str

bpy.path.display_name_from_filepath(name)¶

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

Parameters:: name (str) – The file path to convert.
Returns:: The display name.
Return type:: str

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

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

Parameters:

filepath (str) – The file path.
ext (str) – The extension to check for, can be a compound extension. Should start with a dot, such as ‘.blend’ or ‘.tar.gz’.
case_sensitive (bool) – Check for matching case when comparing extensions.

Returns:

The file path with the given extension.

Return type:

str

bpy.path.is_subdir(path, directory)¶

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

Parameters:: path (str | bytes) – An absolute path.
Returns:: Whether or not the path is a subdirectory.
Return type:: bool

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

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

Parameters:

path (str) – a directory to scan.
recursive (bool) – Also return submodule names for packages.
package (str) – 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[str]

bpy.path.native_pathsep(path)¶

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

Parameters:: path (str) – The path to replace.
Returns:: The path with system native separators.
Return type:: str

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[str]) – Sequence of directory paths.
Returns:: A unique list of paths.
Return type:: list[str]

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

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

Parameters:

path (str | bytes) – An absolute path.
start (str | bytes) – Relative to this path, when not set the current filename is used.

Returns:

The relative path.

Return type:

str

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 (str) – The path name to resolve.
Returns:: The resolved path.
Return type:: str