{"id":614,"library":"backports-tarfile","title":"Backports Tarfile","description":"backports.tarfile provides a backport of the CPython standard library's `tarfile` module, allowing users on older Python versions (>=3.8) to access newer features and bug fixes related to tar archive handling. The current version is 1.2.0, released recently, with several updates in Spring 2024.","status":"active","version":"1.2.0","language":"python","source_language":"en","source_url":"https://github.com/jaraco/backports.tarfile","tags":["tarfile","backport","archive","compression","backports"],"install":[{"cmd":"pip install backports-tarfile","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Runtime dependency, specifically for Python versions where `tarfile` features are not yet native.","package":"python","optional":false}],"imports":[{"note":"Using `import tarfile` will only load the standard library's `tarfile` module. To access the backported features, you must import it from the `backports` namespace.","wrong":"import tarfile","symbol":"tarfile","correct":"from backports import tarfile"}],"quickstart":{"code":"import os\nfrom backports import tarfile\n\n# Create a dummy file\nwith open('example.txt', 'w') as f:\n    f.write('Hello, backported tarfile!')\n\n# Create a tar.gz archive\nwith tarfile.open('example.tar.gz', 'w:gz') as tar:\n    tar.add('example.txt')\n\nprint('Archive created: example.tar.gz')\n\n# Extract the archive\nwith tarfile.open('example.tar.gz', 'r:gz') as tar:\n    tar.extractall(path='./extracted_archive')\n\nprint('Archive extracted to ./extracted_archive')\n\n# Clean up\nos.remove('example.txt')\nos.remove('example.tar.gz')\nos.remove('./extracted_archive/example.txt')\nos.rmdir('./extracted_archive')","lang":"python","description":"This example demonstrates how to create and extract a gzipped tar archive using the backported `tarfile` module. The API is identical to the standard library's `tarfile`."},"warnings":[{"fix":"Ensure `backports-tarfile` is explicitly installed. Sometimes, temporarily downgrading `setuptools` or using conditional `pip install backports.tarfile` can resolve it.","message":"ImportError due to namespace package conflicts, particularly with `setuptools` versions (e.g., 71.0.0+). Users might encounter `ImportError: cannot import name 'tarfile' from 'backports'`.","severity":"gotcha","affected_versions":"All versions, especially with specific `setuptools` and older Python combinations (e.g., Python 3.8)."},{"fix":"Exercise caution when using extraction filtering on older Python versions. Always refer to CVE records for the most up-to-date security information and consider additional validation.","message":"Security Vulnerabilities in Backported `tarfile` Extraction Filtering (pre-Python 3.12). The backported tarfile extraction filtering feature, intended for security, was incomplete and could introduce new security issues if projects switched from custom inspection to relying solely on these filters.","severity":"gotcha","affected_versions":"Python versions prior to 3.12, where `tarfile` extraction filtering was backported."},{"fix":"Only install and use `backports.tarfile` if your Python runtime explicitly lacks the `tarfile` features you require and the backport provides them (e.g., specific compression algorithms or filters only available in newer Python stdlib versions). Use conditional imports (e.g., `if sys.version_info < (3, 14): from backports.zstd import tarfile`) if targeting a range of Python versions.","message":"Misunderstanding its purpose: This library is a backport. If your Python version natively includes the `tarfile` features you need, you should use the standard library's `tarfile` directly, rather than the backport, to avoid unnecessary dependencies or potential conflicts.","severity":"gotcha","affected_versions":"All versions, for users on Python versions that already include the desired `tarfile` features."},{"fix":"Explicitly use the `filter` argument (e.g., `filter='data'`, `filter='fully_trusted'`, or `filter='tar'`) when extracting tar archives to control this behavior and suppress the deprecation warning. This ensures forward compatibility and consistent behavior with Python 3.14 and later versions.","message":"Python 3.14 will, by default, filter extracted tar archives and reject files or modify their metadata. This DeprecationWarning appears when `tarfile.extractall()` or `tar.extract()` is called without explicitly providing the `filter` argument.","severity":"gotcha","affected_versions":"Appears in Python 3.13+ when using `tarfile` extraction without specifying a `filter` argument, due to a breaking change in default behavior in Python 3.14+."}],"env_vars":null,"last_verified":"2026-05-12T16:42:39.056Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure `backports.tarfile` is explicitly installed and potentially try uninstalling and reinstalling it (`pip uninstall backports.tarfile && pip install backports.tarfile>=1.2.0`). If `setuptools` is involved, upgrading `setuptools` or ensuring its dependencies are correctly handled might resolve the conflict. Sometimes, removing a conflicting 'empty' `backports` namespace package (a directory containing only an `__init__.py` file) can also help.","cause":"This error often occurs due to conflicts with the `setuptools` library or issues with Python's namespace package handling, where an 'empty' `backports` package might be shadowing the intended `backports.tarfile` module, especially on Python versions where `setuptools` vendors parts of `backports`.","error":"ImportError: cannot import name 'tarfile' from 'backports'"},{"fix":"Install the `backports.tarfile` package using pip: `pip install backports-tarfile`.","cause":"This means the `backports` namespace package, which `backports.tarfile` resides under, is not installed or discoverable in your Python environment.","error":"ModuleNotFoundError: No module named 'backports'"},{"fix":"Ensure `backports.tarfile` is installed and that your code correctly imports and uses the backported module. If you're explicitly importing `tarfile` directly, ensure that the `backports.tarfile` is taking precedence or is directly imported (e.g., `import backports.tarfile as tarfile`). If the issue persists, verify your Python version meets the minimum requirements for the specific feature you are trying to backport, or consider upgrading your Python environment if the feature is not supported by `backports.tarfile` on your current version. If using `pip`, ensure it's up-to-date (`pip install --upgrade pip`).","cause":"This error arises when trying to use newer features of the `tarfile` module, such as `data_filter`, which were introduced in later Python versions (e.g., Python 3.12+), on an older Python environment where `backports.tarfile` is either not correctly replacing the standard library module or the Python version is too old to support even the backported feature.","error":"AttributeError: module 'tarfile' has no attribute 'data_filter'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"1.2.0","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.1,"disk_size":"18.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.1,"disk_size":"18.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.01,"mem_mb":1.1,"disk_size":"18M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":1.1,"disk_size":"18M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"19.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"19.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.03,"mem_mb":1.7,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.7,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.3,"disk_size":"11.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.3,"disk_size":"11.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":0.03,"mem_mb":1.3,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.3,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.4,"disk_size":"11.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.4,"disk_size":"11.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":0.02,"mem_mb":1.2,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.2,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.6,"disk_size":"17.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.6,"disk_size":"17.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.02,"mem_mb":1.6,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.6,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}