How to avoid forbidden characters in file names?

[ultram4rine]

Hi, real life example, asterisk sign * in filename on NTFS filesystem is forbidden. Any way to avoid it using path formats?

[ultram4rine]

I guess substitute will help:

substitute:
  \*: _

need to test it

[CAOShurong]

In beets, sanitization of forbidden filesystem characters (like *, :, ?, <, >, |) for generated file paths is actually handled out of the box, but there are a few important nuances depending on what you are trying to achieve:

1. Built-in replace: configuration (Recommended for destination paths)

By default, beets already includes a regex replacement map specifically for Windows / NTFS reserved characters (beets/config_default.yaml):

replace:
    '[<>:\?\*\|]': _
    '\"': _
    '[\\/]': _
    '^\.': _
    '\.$': _
    '[\x00-\x1f]': _
    '^-': _
    '\s+$': ''
    '^\s+': ''

This automatically converts * into _ when calculating destination paths on disk without altering your metadata in the beets database.

Note: If you define a custom replace: block in your config.yaml, beets replaces the entire mapping rather than merging keys. If you customize replace:, make sure to keep the reserved character regex:

replace:
    '[<>:\?\*\|]': _   # Replaces * and other NTFS reserved characters
    # other custom regex patterns...

2. Field-level handling in Path Formats via inline plugin

If you want custom character substitution only for specific fields inside your paths: templates (for example, replacing * with an empty string or hyphen instead of an underscore):
You can enable the built-in inline plugin:

plugins: inline

item_fields:
    safe_title: title.replace('*', '_')
    safe_album: album.replace('*', '_')

paths:
    default: $albumartist/$safe_album/$track $safe_title

3. Difference from the substitute plugin

The substitute plugin modifies the metadata tags stored in your beets database and audio files during import/tagging. If you only want to sanitize the filenames on the NTFS volume while preserving the original track title with * in the database / audio tags, using replace: or an inline path format field is the cleaner solution.

4. Non-ASCII & Unicode sanitization

If you also encounter issues with Unicode / accent characters on NTFS or Samba network mounts, you can enable:

asciify_paths: yes

which transliterates non-ASCII characters to ASCII equivalents before replace: is applied.