Skip to content

Support path-like objects in shutil.which()  #161788

Closed

Description

@Builder106

shutil.which() accepts a bytes command and returns a bytes path. It also accepts path-like command objects, but a path-like object whose __fspath__() method returns bytes raises TypeError instead of behaving like the equivalent direct bytes value.

import shutil


class BytesPath:
    def __fspath__(self):
        return b"python3"


print(shutil.which(b"python3"))
print(shutil.which(BytesPath()))

On CPython main, the first call returns a bytes path and the second fails:

b'/usr/bin/python3'
TypeError: Can't mix strings and bytes in path components

which() checks whether cmd is bytes before resolving the path-like object. It then decodes PATH to str, while os.path.split() has resolved the command to bytes. Calling os.fspath(cmd) before choosing the string or bytes path keeps the command and search path on the same type.

CPython versions tested on

  • CPython main branch (3.16.0a2+)

Operating systems tested on

  • Linux ARM64

Linked PRs

Activity

  1. added
    type-bugAn unexpected behavior, bug, or error
    stdlibStandard Library Python modules in the Lib/ directory
    on Nov 11, 2026
  2. picnixz commented on Nov 11, 2026

    @picnixz
    Member

    I don't think it's a bug. It accepts path-like objects by change I think, not by contract. Supporting bytes was a new feature because it also returned bytes. But looking at older issues, it's not clear whether shutil.which() should support path-like objects (see #90883, #67430 as well)

  3. added
    type-featureA feature request or enhancement
    pendingThe issue will be closed if no feedback is provided
    and removed
    type-bugAn unexpected behavior, bug, or error
    on Nov 11, 2026
  4. changed the title [-]shutil.which() fails for bytes-backed path-like commands[/-] [+]Support path-like objects in shutil.which() [/+] on Nov 11, 2026
  5. Builder106 commented on Nov 11, 2026

    @Builder106
    ContributorAuthor

    @picnixz

    Oh right, hadn't considered that path-like support might be accidental. I was thinking the return type could follow whatever os.fspath() returns, but I do see your point.

    Do you think it's worth supporting that, or should we leave path-like commands unsupported?

  6. picnixz commented on Nov 11, 2026

    @picnixz
    Member

    Considering how hard it was for adding the bytes support, I'd rather not add pathlike support. I'd prefer that every functions that seems to work with pathlike in shutil to be considered accidental and decide later whether to add pathlike support entirely or not. Semantically, it's a bit hard to determine whether cmd should be considered a path or not in the first place (e.g., shutil.which('ls') returns a path but this doesn't mean that the command itself should be a path).

  7. vstinner commented on Nov 13, 2026

    @vstinner
    Member

    Multiple shutil functions already accept "path-like objects", so IMO it makes sense to support path-like in which() as well.

    But looking at older issues, it's not clear whether shutil.which() should support path-like objects (see #90883, #67430 as well)

    The first one is more about "supporting bytes paths". which() already accepts bytes:

    >>> import shutil
    >>> shutil.which('python')
    '/usr/bin/python'
    >>> shutil.which(b'python')
    b'/usr/bin/python'
    

    The second issue was about adding path-like support to shutil.copyfile() and it was closed because shutil.copyfile() already supported path-like objects.

    Considering how hard it was for adding the bytes support, I'd rather not add pathlike support.

    I don't understand well the relationship between these two things. which() already supports bytes. The propose patch is just to add cmd = os.fspath(cmd) (and associated tests). I don't think that one line is hard to maintain.

  8. Builder106 commented on Nov 13, 2026

    @Builder106
    ContributorAuthor

    Thanks @vstinner, this is what I had in mind with the patch: resolve cmd with os.fspath() first, then use the existing str or bytes handling. But I think I'm gonna wait to hear what the other maintainers think.

  9. picnixz commented on Nov 13, 2026

    @picnixz
    Member

    I don't understand well the relationship between these two things. which() already supports bytes

    I think I misread the issue. However, my objection to semantics still remains. I don't think cmd is meant to be a path. That being said, I actually looked at subprocess.run()'s args which are similar and we also added support to pathlike objects, so I guess we don't really care about semantics.

  10. removed
    pendingThe issue will be closed if no feedback is provided
    on Nov 13, 2026
  11. vstinner commented on Nov 13, 2026

    @vstinner
    Member

    To me, cmd is a relative path and shutil.which() gets its absolute path. So it makes sense to support os.fspath().

  12. added a commit that references this issue on Nov 14, 2026
  13. added a commit that references this issue on Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    stdlibStandard Library Python modules in the Lib/ directorytype-featureA feature request or enhancement

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions