ytdl-org/youtube-dl · warning · XAttrUnavailableError

Couldn't find a tool to set the xattrs. Install either the p

Error message

Couldn't find a tool to set the xattrs. Install either the python 'pyxattr' or 'xattr' modules, or the GNU 'attr' package (which contains the 'setfattr' tool).

What it means

Raised as XAttrUnavailableError by write_xattr in youtube_dl.utils on Linux when no xattr backend could be found: the pyxattr/xattr python modules are not importable and the setfattr CLI tool is absent from PATH. It fires only on sys.platform starting with 'linux'; the tool then cannot store metadata (like filesize) in extended attributes.

Source

Thrown at youtube_dl/utils.py:6238

                cmd = ([encodeFilename(executable, True)]
                       + [encodeArgument(o) for o in opts]
                       + [encodeFilename(path, True)])

                try:
                    p = subprocess.Popen(
                        cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, stdin=subprocess.PIPE)
                except EnvironmentError as e:
                    raise XAttrMetadataError(e.errno, e.strerror)
                stdout, stderr = process_communicate_or_kill(p)
                stderr = stderr.decode('utf-8', 'replace')
                if p.returncode != 0:
                    raise XAttrMetadataError(p.returncode, stderr)

            else:
                # On Unix, and can't find pyxattr, setfattr, or xattr.
                if sys.platform.startswith('linux'):
                    raise XAttrUnavailableError(
                        "Couldn't find a tool to set the xattrs. "
                        "Install either the python 'pyxattr' or 'xattr' "
                        "modules, or the GNU 'attr' package "
                        "(which contains the 'setfattr' tool).")
                else:
                    raise XAttrUnavailableError(
                        "Couldn't find a tool to set the xattrs. "
                        "Install either the python 'xattr' module, "
                        "or the 'xattr' binary.")


def random_birthday(year_field, month_field, day_field):
    start_date = datetime.date(1950, 1, 1)
    end_date = datetime.date(1995, 12, 31)
    offset = random.randint(0, (end_date - start_date).days)
    random_date = start_date + datetime.timedelta(offset)
    return {
        year_field: str(random_date.year),

View on GitHub (pinned to 956b8c5855)

Solutions

Install the GNU attr package (Debian/Ubuntu: apt-get install attr; Fedora: dnf install attr) which provides setfattr.
Or install a python backend: pip install xattr (or pyxattr>=0.5.0).
If xattr metadata is optional, remove --xattr-set-filesize from your command/config file (~/.config/youtube-dl/config).
For containers, add the package to the image rather than relying on the host.

Example fix

# before
youtube-dl --xattr-set-filesize URL  # XAttrUnavailableError: Couldn't find a tool to set the xattrs...

# after
apt-get install -y attr && youtube-dl --xattr-set-filesize URL

Defensive patterns

Strategy: try-catch

Validate before calling

import shutil, importlib.util, sys

def xattr_backend_available():
    if importlib.util.find_spec('xattr'):
        return True
    return bool(shutil.which('setfattr') or shutil.which('xattr'))

# on linux, gate --xattr-set-filesize on xattr_backend_available()

Try / catch

from youtube_dl.utils import write_xattr, XAttrUnavailableError
try:
    write_xattr(path, key, value)
except XAttrUnavailableError as e:
    log.debug('xattr write skipped: %s', e)  # non-fatal, download already succeeded

Prevention

Install the attr package (setfattr) or pip install xattr in base images that use --xattr-set-filesize.
Probe for a backend at startup (code above) and disable the flag when absent.
Never treat xattr failure as fatal — wrap write_xattr calls in except XAttrUnavailableError.

When it happens

Trigger: Running with --xattr-set-filesize (or calling write_xattr) on Linux where 'import xattr' raises ImportError and either setfattr is not in PATH or the earlier CLI branch could not run. The final else branch raises the Linux-specific install message.

Common situations: Minimal Docker containers or slim images without the attr package; CI runners; systems where the filesystem does not support xattrs and the package was never installed; users assuming xattr support is built in.

Related errors

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