os.walk calls itself recursively and that limits the directory depth it can "walk" into.

On Linux, one can create directory hierarchies deeper than that.

For some more details see there:

https://github.com/borgbackup/borg/issues/380

Note: similar issues can be seen in other stdlib recursive filesystem-related functions also.

I think the code should be left as-is (we've used some variation of recursion for walking a very long time with no reported real-world problems).  Perhaps a documentation note can be added to the effect that the there is a recursion limit and that it can be changed by the user if needed.

I've actually tried to test the recursion limit on my Mac OS X. It seems that I cannot create any subdirectories after around 500 subdir depth. I guess it's related to the allowed path length (<1024 chars?).

There is another limitation with os.walk
it also cannot go very deep inside tree because of scandir can throw 
OSError(36, 'File name too long')

I have wrote tests for both cases:

https://gist.github.com/grubberr/3367f1d605e292103b576a17a46ef3c3

tested on linux only

on MacOS it throw 'File name too long' for 1-st test too
set sys.settrecursionlimit to lower values

I'm not too sure about documenting the recursive limit here. There's a few other recursive functions in the os library (such as makedirs()) and if we note the recursive limit for os.walk then all of them should be noted too, but that doesn't seem quite right to me.

I agree with Stanley. The documentation for os is clear that recursion is used and the documentation for RecursionError links to getrecursionlimit(). This seems sufficient.