This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: "pathlib.Path.link_to()" and "pathlib.Path.symlink_to()" have reversed usage
Type: behavior Stage: resolved
Components: Library (Lib) Versions: Python 3.8
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: Nosy List: Rockmizu, barneygale, nanjekyejoannah, pitrou, yota moteuchi
Priority: normal Keywords:

Created on 2020-01-10 17:50 by Rockmizu, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Messages (6)
msg359745 - (view) Author: Rockmizu (Rockmizu) Date: 2020-01-10 17:50
Python version: Python 3.8.1 (tags/v3.8.1:1b293b6, Dec 18 2019, 23:11:46) [MSC v.1916 64 bit (AMD64)] on win32

The usage of symlink_to() is link.symlink_to(target)
while the usage of link_to() is target.link_to(link).
This could be confusing.

Here is an example:

>>> import pathlib
>>> target = pathlib.Path('target.txt')
>>> p1 = pathlib.Path('symlink.txt')
>>> p2 = pathlib.Path('hardlink.txt')
>>> p1.symlink_to(target)
>>> p2.link_to(target)  # expected usage
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "D:\Program Files\Python38\lib\", line 1346, in link_to
    self._accessor.link_to(self, target)
FileNotFoundError: [WinError 2] The system cannot find the file specified: 'hardlink.txt' -> 'target.txt'
>>> target.link_to(p2)  # current usage

Since os.symlink() and have the same argument order,

>>> import os
>>> os.symlink('target.txt', 'symlink.txt')
>>>'target.txt', 'hardlink.txt')

it would be nicer if the pathlib has the same argument order too.
msg359747 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2020-01-10 18:35
Ahah. Nice catch!

Well, it's a pity this got overlooked when we added Path.link_to().  But I'm afraid it's late to change it now, since this has been released, and changing the argument order would break existing code in potentially dangerous ways.

Note the original issue where this was added was issue26978.
msg359748 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2020-01-10 18:37
Closing as won't fix.  If you feel strongly about this, I would suggest to bring the discussion on python-dev:
msg364057 - (view) Author: Barney Gale (barneygale) * Date: 2020-03-12 23:40
Per discussion on the mailing list, I'd like to request that this bug be re-opened.
msg364058 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2020-03-12 23:44
Am hesitant on re-opening this.

I think it sounds more meaningful to open a new issue for the new
suggestion that requires deprecating this
current behavior and introducing the new intended functionality.


On Thu, Mar 12, 2020 at 8:40 PM Barney Gale <> wrote:

> Barney Gale <> added the comment:
> Per discussion on the mailing list, I'd like to request that this bug be
> re-opened.
> ----------
> nosy: +barneygale
> _______________________________________
> Python tracker <>
> <>
> _______________________________________

Joannah Nanjekye

*"You think you know when you learn, are more sure when you can write, even
more when you can teach, but certain when you can program." Alan J. Perlis*
msg385249 - (view) Author: yota moteuchi (yota moteuchi) Date: 2021-01-19 09:33
one option to could be to create a hardlink_to() method which is link.hardlink_to(target) and in a few release, deprecate link_to ? :)
Date User Action Args
2022-04-11 14:59:25adminsetgithub: 83472
2021-01-19 09:33:11yota moteuchisetnosy: + yota moteuchi
messages: + msg385249
2020-03-12 23:44:58nanjekyejoannahsetmessages: + msg364058
2020-03-12 23:40:32barneygalesetnosy: + barneygale
messages: + msg364057
2020-03-11 08:48:30eric.smithlinkissue39925 superseder
2020-01-10 18:37:27pitrousetstatus: open -> closed
resolution: wont fix
messages: + msg359748

stage: resolved
2020-01-10 18:35:20pitrousetnosy: + nanjekyejoannah
messages: + msg359747
2020-01-10 18:11:41xtreaksetnosy: + pitrou
2020-01-10 17:50:14Rockmizucreate