New submission from Andrew Svetlov: Hi. On reading the doc for pathlib I've stuck with `.rename()` and `.replace()` (https://docs.python.org/3/library/pathlib.html#pathlib.Path.rename). What's the difference? Going to pathlib's source code I've figured out that methods are use different functions from `os` module: `os.rename()` and `os.replace()`. But the documentation for `os` module is not obvious too: the docs for both functions are almost equal from my perspective, the only significant difference is that `os.rename()` suggests to use `os.replace()` for cross-compatibility. Could anybody explain the difference? Also, at least the doc for `pathlib.Path.rename` worth to have a sentence like borrowed from `os.rename`: "If you want cross-platform overwriting of the destination, use replace()." ---------- assignee: docs@python components: Documentation keywords: easy messages: 273836 nosy: asvetlov, docs@python, pitrou priority: low severity: normal status: open title: Docs: the difference between rename and replace is not obvious type: behavior versions: Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue27886> _______________________________________