pathlib.UnsupportedOperation

pathlib raises it for things that cannot work here: creating a WindowsPath on Linux (or a PosixPath on Windows), owner() and group() without pwd/grp, symlink_to() or readlink() where the OS lacks them. It subclasses NotImplementedError, so older except clauses still catch it.

InheritsBaseException›Exception›RuntimeError›NotImplementedError›UnsupportedOperation
pathlib exceptionPython 3.13+
pathlib.UnsupportedOperation(*args)
Raised by
PosixPath('x') on Windows, WindowsPath('x') elsewhere, Path.owner() / group() on Windows
Message
"cannot instantiate 'PosixPath' on your system" or "WindowsPath.owner() is unsupported on this system"
Quick fix
Use Path(...) and the pure classes; guard OS-specific calls with os.name
Watch out
Defined in pathlib._abc — tracebacks show pathlib._abc.UnsupportedOperation

Parameters

NameTypeRequiredDescription
*argsobjectnoThe message, as for any exception.

Common patterns

Owner name where supported
owner() needs the pwd module (POSIX only).
from pathlib import Path, UnsupportedOperation
try:
    who = Path('data.db').owner()
except UnsupportedOperation:
    who = None
Code that must also run on 3.12 and older
Catch the base class — older versions raised a plain NotImplementedError.
try:
    target = link.readlink()
except NotImplementedError:
    target = None

Examples

1. Where it sits in the hierarchy
from pathlib import UnsupportedOperation [c.__name__ for c in UnsupportedOperation.__mro__]
Returns
['UnsupportedOperation', 'NotImplementedError', 'RuntimeError', 'Exception', 'BaseException', 'object']
2. Its real module
from pathlib import UnsupportedOperation UnsupportedOperation.__module__
Returns
'pathlib._abc'
3. The foreign concrete class raises it
import os from pathlib import PosixPath, WindowsPath, UnsupportedOperation foreign = PosixPath if os.name == 'nt' else WindowsPath try: foreign('x') except UnsupportedOperation as e: result = str(e) == f"cannot instantiate {foreign.__name__!r} on your system" result
Returns
True
4. except NotImplementedError still catches it
from pathlib import UnsupportedOperation try: raise UnsupportedOperation('not here') except NotImplementedError as e: result = type(e).__name__ result
Returns
'UnsupportedOperation'
5. The traceback line is module-qualified
from pathlib import UnsupportedOperation raise UnsupportedOperation('symlinks are unavailable')
Returns
pathlib._abc.UnsupportedOperation: symlinks are unavailable

Pitfalls

1. Catching io.UnsupportedOperation instead
io has an unrelated UnsupportedOperation (raised for unreadable/unwritable streams). It does not catch the pathlib one.
io.UnsupportedOperation
import io
from pathlib import UnsupportedOperation
issubclass(UnsupportedOperation, io.UnsupportedOperation)
False
pathlib.UnsupportedOperation
import pathlib
from pathlib import UnsupportedOperation
UnsupportedOperation is pathlib.UnsupportedOperation
True
2. Creating a foreign concrete path
To work with a Linux path on Windows (or the reverse), use the pure class of that flavour.
foreign Path class
import os
from pathlib import PosixPath, WindowsPath
foreign = PosixPath if os.name == 'nt' else WindowsPath
try:
    foreign('/srv/app')
except NotImplementedError as e:
    result = type(e).__name__
result
'UnsupportedOperation'
pure flavour
from pathlib import PurePosixPath
PurePosixPath('/srv/app').name
'app'

When to use

Use it
  • except UnsupportedOperation around owner(), group(), symlink_to(), readlink() in portable code
  • Raising it from your own PathBase-style classes for operations they cannot do
Reach for something else
  • Supporting 3.12 or older → catch NotImplementedError, which covers both

Notes

CPython impl
Lib/pathlib/_abc.py: class UnsupportedOperation(NotImplementedError); re-exported as pathlib.UnsupportedOperation
Added in 3.13
PosixPath / WindowsPath on the wrong OS, owner(), group(), readlink(), symlink_to() and hardlink_to() raised NotImplementedError before
Messages
"cannot instantiate 'WindowsPath' on your system"; on Windows "WindowsPath.owner() is unsupported on this system"

FAQ

Something created a PosixPath on Windows — typically by unpickling a path saved on Linux, or by naming the class directly. Only the class for the running OS can exist; use PurePosixPath for foreign paths or rebuild with Path(str(p)).