ytdl-org/youtube-dl · warning · XAttrUnavailableError

python-pyxattr is detected but is too old. youtube-dl requir

Error message

python-pyxattr is detected but is too old. youtube-dl requires %s or above while your version is %s. Falling back to other xattr implementations

What it means

Raised as XAttrUnavailableError by _xattr_set() in youtube_dl.utils when writing extended attributes (e.g. embedding metadata via --xattr-set-filesize). The 'xattr' import resolved to python-pyxattr (it has a .set attribute), but its __version__ is below 0.5.0, which is the first release supporting unicode arguments (issue #5498). youtube-dl refuses to use it rather than crash on unicode paths, and despite the message text the code raises instead of actually falling back (the TODO 'fallback to CLI tools' is unimplemented).

Source

Thrown at youtube_dl/utils.py:6179

            current_row.append(color)

    return width, height, pixels


def write_xattr(path, key, value):
    # This mess below finds the best xattr tool for the job
    try:
        # try the pyxattr module...
        import xattr

        if hasattr(xattr, 'set'):  # pyxattr
            # Unicode arguments are not supported in python-pyxattr until
            # version 0.5.0
            # See https://github.com/ytdl-org/youtube-dl/issues/5498
            pyxattr_required_version = '0.5.0'
            if version_tuple(xattr.__version__) < version_tuple(pyxattr_required_version):
                # TODO: fallback to CLI tools
                raise XAttrUnavailableError(
                    'python-pyxattr is detected but is too old. '
                    'youtube-dl requires %s or above while your version is %s. '
                    'Falling back to other xattr implementations' % (
                        pyxattr_required_version, xattr.__version__))

            setxattr = xattr.set
        else:  # xattr
            setxattr = xattr.setxattr

        try:
            setxattr(path, key, value)
        except EnvironmentError as e:
            raise XAttrMetadataError(e.errno, e.strerror)

    except ImportError:
        if compat_os_name == 'nt':
            # Write xattrs to NTFS Alternate Data Streams:
            # http://en.wikipedia.org/wiki/NTFS#Alternate_data_streams_.28ADS.29

View on GitHub (pinned to 956b8c5855)

Solutions

Upgrade python-pyxattr to >= 0.5.0 (pip install -U pyxattr).
Or uninstall pyxattr so youtube-dl can use the alternate 'xattr' module or the setfattr CLI tool.
Or install the GNU attr package / setfattr tool as an alternative backend.
If you do not need xattr metadata, drop --xattr-set-filesize.

Example fix

# before: python-pyxattr 0.4.x installed
youtube-dl --xattr-set-filesize URL  # XAttrUnavailableError: python-pyxattr is detected but is too old...

# after
pip install -U 'pyxattr>=0.5.0'
youtube-dl --xattr-set-filesize URL

Defensive patterns

Strategy: validation

Validate before calling

def pyxattr_ok():
    try:
        import xattr
    except ImportError:
        return False
    if hasattr(xattr, 'set'):
        from youtube_dl.utils import version_tuple
        return version_tuple(xattr.__version__) >= version_tuple('0.5.0')
    return True  # alternate 'xattr' module

# before --xattr-set-filesize: if not pyxattr_ok(): upgrade or disable the flag

Try / catch

from youtube_dl.utils import write_xattr, XAttrUnavailableError
try:
    write_xattr(path, key, value)
except XAttrUnavailableError:
    pass  # metadata is optional; log and continue

Prevention

Pin pyxattr>=0.5.0 in requirements when using --xattr-set-filesize.
Treat xattr metadata as optional: always catch XAttrUnavailableError and continue the download.
In provisioning scripts, uninstall stale distro pyxattr and pip-install a current version.

When it happens

Trigger: Running with --xattr-set-filesize (or any code path calling write_xattr) on a machine where python-pyxattr < 0.5.0 is importable. version_tuple(xattr.__version__) < version_tuple('0.5.0') triggers the raise.

Common situations: Old distro-packaged pyxattr (pre-2014 versions) still installed; embedded/bundled python environments shipping a stale pyxattr; enabling xattr metadata on a NAS or container image with ancient packages.

Related errors

AI-assisted analysis of ytdl-org/youtube-dl@956b8c5855 (2026-08-14). Data as JSON: /api/errors/8b1a85d3805e75be. Report an issue: GitHub.