bpy.props.StringProperty has [‘FILE_PATH’, ‘DIR_PATH’, ‘FILE_NAME’, ‘BYTE_STRING’, ‘PASSWORD’, ‘NONE’] as options, but nowhere are those documented.

It seams simple enough to guess what FILE_PATH, DIR_PATH, and FILE_NAME do, but what do they all do?
Are these actually documented somewhere?


1 Answer 1




Use for storing file paths. Adds a button to the UI property markup, that when used sets the string to the file path chosen. Option to make it a relative path.


Use for storing directory paths. Adds a button to the UI property markup, that when used sets the string to the directory path chosen.


AFAICT is for, as the name suggests storing a filename. Filenames cannot contain certain characters. It doesn't appear to in anyway auto-parse. The Paint Palettes addon uses the subtype for preset file names. The following method is used to parse out illegal / invalid chars.

def as_filename(name):  # could reuse for other presets
    for char in " !@#$%^&*(){}:\";'[]<>,.\\/?":
        name = name.replace(char, '_')
    return name.lower().strip()


Stores the string as a utf-8 encoded byte string. Equivalent of "string".encode().


Displays asterisks (*) when input is typed in the UI. Stores the string as entered.


Default. None of the above.

Run a script and see.

Like any code we can run and see, the worst thing that can happen is your computer explodes, starts a fire an burns down your city.

Here is a test script to set a string property of each subtype to the window manager, and display them in a panel (using the simple panel template code) as well as write their value to system console on change.

import bpy
from bpy.props import StringProperty


def print_value(subtype):
    def print_value(self, context):
        print(subtype, getattr(self, subtype))
    return print_value

for st in subtypes:
            StringProperty(subtype=st, update=print_value(st)))

class HelloWorldPanel(bpy.types.Panel):
    """Creates a Panel in the Object properties window"""
    bl_label = "Hello World Panel"
    bl_idname = "OBJECT_PT_hello"
    bl_space_type = 'PROPERTIES'
    bl_region_type = 'WINDOW'
    bl_context = "object"

    def draw(self, context):
        wm = context.window_manager
        layout = self.layout
        for st in subtypes:
            layout.prop(wm, st)

def register():

def unregister():

if __name__ == "__main__":

Here is the result.

enter image description here

and the result of setting all to "xxxxxx" in the panel written to system console.

FILE_PATH xxxxxx
DIR_PATH xxxxxx
FILE_NAME xxxxxx
BYTE_STRING b'xxxxxx'
NONE xxxxxx

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .