Add `follow_links` parameter to `shutil.make_archive()`

[cowgoesmoo69]

Feature or enhancement

Proposal:

A previous issue, #81782, discussed the possibility of modifying shutil.make_archive() so that symbolic links could be followed when creating zip files. The issue states that symbolic links are not followed. My testing in Linux revealed to me that os.walk(), used within the _make_zipfile() function, by default does follow symbolic links to files, but does not follow symbolic links to directories.

From my understanding of the documentation for os.walk() I think the default behaviour is probably quite intentional, since if a symbolic link to a directory points to a parent directory of the location of the link, os.walk() will become trapped in a process of infinite recursion. But os.walk() does have a followlinks parameter than can be set to True to override the default behaviour and resolve symbolic links to directories.

I originally started looking into any of this because I was using shutil.make_archive() in a backup script to create a compressed tarball from a folder that contains symbolic links to many files and directories of interest, and the behaviour with symbolic links was not quite what I expected. The tarfile module has a dereference parameter available that can be set to True to override the default behaviour and resolve symbolic links to files and directories.

I also investigated the behaviour with hard links for completeness.

Default behaviour when creating a "zip" with shutil.make_archive():

• Hard links are resolved. Multiple hard links to the same file results in multiple copies of the file being added to the archive.
• Symbolic links to files are resolved.
• Symbolic links to directories are not resolved.

Modified behaviour when creating a "zip" with os.walk() set to follow links:

• Symbolic links to directories are resolved.
• Hard links and symbolic links to files behaviour is unchanged.

Default behaviour when creating compressed tarball:

• Hard links are resolved intelligently. That is to say that multiple hard links to a single file result in only one copy of the file being added to the archive, other links remain as hard links. When a tarball is extracted in its entirety, the hard links are resolved and multiple copies of the file are produced in the output.
• Symbolic links to files are preserved as symbolic links.
• Symbolic links to directories are preserved as symbolic links.

Modified behaviour when creating compressed tarball set to dereference:

• Hard links are resolved in the same way as for "zip", multiple hard links to a file results in multiple copies of the file in the archive.
• Symbolic links to files are resolved.
• Symbolic links to directories are resolved.

My proposal is to include an optional follow_links parameter to the shutil.make_archive() function that is passed to the _make_zipfile() and _make_tarball() functions, defaulting to False to preserve the existing behaviour as the default.

I am of course happy to discuss the proposal. Since the features exist in the underlying functions I feel it is reasonable to provide the option to the user, along with detailed documentation of what it will do. In #81782 a member of the development team said they felt it was a reasonable addition, and the issue remains open.

I have prepared a forked branch with commits for the following:

• Add follow_links parameter to the functions in the shutil module, and updates to docstrings to document the default and modified behaviour in detail.
• Add tests to test_shutil.py to check the behaviour of symlinks on systems where they are supported.

If it is felt that this would be a useful addition I can finalise things and submit a PR for review. Thank you for taking the time to read this.

Has this already been discussed elsewhere?

For completeness, existing APIs already have a follow_symlinks parameter: #81782 (comment).

Links to previous discussion of this feature:

• shutil.make_archive does not follow symlinks for zip archives #81782

Linked PRs

• gh-139679: Resolve symbolic links to directories when shutil.make_archive() is used to create a zip file #139856

[StanFromIreland]

Hello, in general it is best to open a thread with your idea in the Ideas category of the Python discourse. Also, is this not just a duplicate of #81782?

[cowgoesmoo69]

Thanks for your reply. I will open a thread on the discourse.

I don't think it is a duplicate as the previous issue only relates to the behaviour for zip files created make_archive(); my proposal would allow modifying the default behaviour for both zips and tarballs. Additionally, the previous issue does not quite capture the default behaviour accurately; it states that symbolic links are not followed at all; symbolic links to files are followed, it is only symbolic links to directories that are not.

[picnixz]

I would still categorize this as a duplicate of the previous. The previous issue requests that we follow symlinks. Even if it's inaccurately formulated, we can always change the scope of the issue. What we want to avoid is having multiple issues for the same topic.

Now, your issue actually contains a longer description rather than just a "it doesn't work for now", so I'm going to close the old issue instead as a duplicate of this one to avoid C/C your entire message.

[picnixz]

My 2c: at first glance, a DPO proposal is not really needed because shutil already supports follow_symlinks in other places and with zipfile it appears we do this by default as well (but I don't know if it's still the case in Python 3.13+; could you check this?)

Whatever we do, however, should be consistent and documented. Also, look at the history of shutil to see if there was a reason to remove it if we ever had this, or to see why, when we implemented the hardlink/symlink file support, we didn't consider the directory symlink support.

[cowgoesmoo69]

Thanks for your input, I'll take a look at the history of shutil and come back.

[cowgoesmoo69]

I have referred to Linux/UNIX systems throughout this because I suppose in my mind they're the most likely systems that are going to support symbolic linking, but I appreciate there could be others too.

I've done a bit of digging around:

shutil._make_zipfile() & os.walk()

The _make_zipfile() function first appeared in shutil in 2010 in this commit. 396fad7 The call to os.walk() for creating the list of files to be written to the zipfile has always been made with base_dir as the only parameter.

The os.walk() function has always defaulted to following symbolic links to files and preserving symbolic links to directories. The option to override the behaviour for symbolic links to directories first appeared in 2007 with this commit d8faa36

In terms of the history of the shutil module, the option to resolve symbolic links for directories for zip files has always been there, just never implemented.

shutil._make_tarball() & tarfile

The _make_tarball() function first appeared in shutil in the same commit as _make_zipfile() in 2010. The call to tarfile.open() has always been made with two parameters; one for the archive name and one for which compression scheme to apply.

The tarfile module has always had the dereference parameter available since it was first introduced in 2003.

Again, in terms of the history of the shutil module, the option to resolve symbolic links has always been there, just never implemented.

The 'expected' behaviour for zip files on Linux/UNIX

As a bit of a cross-check, I decided to see what the default behaviour is for the built-in utility provided with Debian 12 for creating zip files. This is zip 3.0.

With zip the default behaviour is that all symbolic links are resolved to their target files and directories and included in the archive.

From the man page an option is provided, -y or --symlinks to 'store symbolic links as such in the zip archive, instead of compressing and storing the file referred to by the link'. From my testing, this preserves symbolic links to both files and directories.

It appears that the default behaviour of shutil._make_zipfile() to resolve symbolic links to files and preserve symbolic links to directories (because that's what os.walk() does by default), does not match the default behaviour of zip.

I checked the man page for zip on Oracle Solaris and it too is zip 3.0.

The 'expected' behaviour for tar files on Linux/UNIX

I then had a look at the default behaviour of tar on Debian 12, which is GNU tar.

With tar the default behaviour is that all symbolic links are preserved, and hard links are de-duplicated when creating the archive. The default behaviour of tarfile matches this.

From the tar man page, two options are provided:
-h or --dereference, to 'follow symlinks; archive and dump the files they refer to'. This resolves symbolic links to files and directories and includes the files the links point to.
--hard-dereference, to 'follow hard links; archive and dump the files they refer to'. This disables the de-duplication of multiple hardlinks to the same file.

From my testing, the behaviour of tarfile is that passing the dereference parameter into its functions is the same as passing both --dereference and --hard-dereference to tar, which may not be desirable because it removes the de-duplication from the tarball.

I also looked at the man page for BSD tar and that only provides a --dereference option for symbolic links. It is not possible to override the de-duplication of multiple hard links to the same file in BSD tar. Looking at the man page for tar on Oracle Solaris, it too does not offer any control over hard link behaviour.

Conclusions

I feel like I'm opening a bit of a can of worms.

I guess I have some questions:

• Is the default behaviour for symbolic links to files and directories for zip files created with shutil supposed to match the default behaviour for the command line version of zip on Linux/UNIX systems, i.e. zip 3.0?

If so, the os.walk() function call to create the list of files to be written to the zipfile needs to have the followlinks parameter passed as True by default so that it lines up with zip behaviour. It is not possible to provide the --symlinks option from zip 3.0 without 'extra steps' because there is not a mode of operation of os.walk() that simply matches it.

• Is the behaviour of the dereference parameter in tarfile supposed to match the behaviour of the same command line argument for GNU tar and BSD tar?

If so, a change of some kind is required to the tarfile module so that the parameter only affects symbolic link behaviour.

• Is it desirable to have a separate parameter in tarfile for controlling the behaviour of hard link de-duplication? Or another way of putting the question might be: Should the behaviour of tarfile match GNU tar or BSD tar? (i.e. broadly, Linux or UNIX behaviour?)

Something I have not yet tested is what happens in the case of dangling symbolic links when using shutil.make_archive(). From poring over the code in shutil I notice that copytree() does something to handle them. I don't currently know what happens if os.walk() or tarfile encounters dangling links, but I think that's something for another day.

Sorry for the wall of text. I wanted to be thorough when investigating things and it's created more questions than it's answered.

[cowgoesmoo69]

Just tested some bits on Windows. I used mklink to make hard links to files and symbolic links to files and directories for testing.

The included zip on the command line in Windows declares itself as being Info-ZIP, Zip 3.1b BETA. It resolves symbolic links to files and directories by default. There does not appear to be any facility to override this behaviour (errors are shown if -y or --symlinks is passed as a parameter).

Also tested the included rar on the command line in Windows. It declares itself as being bsdtar 3.8.1. It follows the default behaviour of tar on Linux/UNIX systems, i.e. preserves symbolic links to files and directories, de-duplicates hardlinks.

While it is not shown in the help available on the command line, passing --dereference as the first parameter does override the default behaviour and causes symbolic links to be resolved. Hardlink de-duplication carries on unaffected.

[cowgoesmoo69]

I've submitted a PR that modifies the default behaviour of shutil.make_archive() to align with the default behaviour of command-line zip utilities on Linux/UNIX/Windows and linked it to this issue.

I think I want to investigate the possibility of giving --symlinks functionality for zip files and the possibility of giving control over tarfile's behaviour independent of this, and raise separate issues for them so it's less messy.