Registry / auth-security / securetar

securetar

JSON →
library2026.4.1pypypi✓ verified 84d ago

SecureTar is a Python library designed for handling encrypted tarfile backups. It acts as a streaming wrapper around Python's standard `tarfile` module, providing robust encryption capabilities. The library is actively maintained with frequent updates, often introducing significant breaking changes related to its file format and API, notably driven by advancements in cryptographic standards and its use in projects like Home Assistant.

pip install securetar
INSTALL
IMPORT
SIG · SECURETAR
S
securetar
auth-securitypythonv2026.4.1
Install
2.4s avg
Import
78ms
Disk
35MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2025.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.081s · 34.4MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.4s · import 0.075s · 35MB
35MB installed
● package 35MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SecureTarFile
from securetar import SecureTarFile
Primary class for creating and reading secure tar archives.
atomic_contents_add
from securetar import atomic_contents_add
Helper function for adding contents to a SecureTarFile in an atomic manner.

This quickstart demonstrates how to create an encrypted tar archive using `SecureTarFile` and add a file to it using `atomic_contents_add`. It then shows how to open and extract content from the created secure archive, requiring the correct password.

import os from pathlib import Path from securetar import SecureTarFile, atomic_contents_add # Create a dummy file for backup dummy_file_path = Path("my_data.txt") dummy_file_path.write_text("This is some sensitive data.") # Define backup path and a password backup_file_path = Path("my_secure_backup.tar") backup_password = os.environ.get('SECURETAR_PASSWORD', 'a_very_secret_password_123') print(f"Creating secure backup to {backup_file_path}...") # Create a secure tar archive with SecureTarFile(backup_file_path, 'w', password=backup_password) as tar_file: atomic_contents_add(tar_file, dummy_file_path, arcname=dummy_file_path.name) print(f"Backup created: {backup_file_path}") # Verify by attempting to read it print(f"Attempting to read from {backup_file_path}...") try: with SecureTarFile(backup_file_path, 'r', password=backup_password) as tar_file: members = tar_file.getnames() print(f"Contents of backup: {members}") # Example of extracting a file extracted_path = Path("extracted_data.txt") tar_file.extract(dummy_file_path.name, path=".") print(f"Extracted '{dummy_file_path.name}' to '{extracted_path}'") extracted_path.unlink() # Clean up except Exception as e: print(f"Error reading backup: {e}") finally: dummy_file_path.unlink() # Clean up original dummy file backup_file_path.unlink() # Clean up backup file
Debug
Known issues
breakingVersion 2026.2.0 introduced a new file format (version 3) using Argon2 for key derivation, Blake2 for subkey derivation, and ChaCha13Poly1305 for encryption. This was a major rewrite breaking most existing implementations.
fix
Ensure your application is updated to handle the new file format and cryptographic primitives. Old backups remain readable, but new ones will use the v3 format. Consult the release notes for detailed migration steps.
affects: >=2026.2.0
breakingVersion 2025.12.0 moved the key derivation function into the library itself, requiring a breaking change in the API. Any custom password-to-key derivation logic outside the library will no longer be compatible.
fix
Adopt the library's internal key derivation mechanisms. Review your code for custom key derivation and update to use `SecureTarFile`'s integrated password handling.
affects: >=2025.12.0
breakingVersion 2025.1.3 added a new file header for encrypted tar files, making the file format *not* backwards compatible for writing new archives, although the library retains the ability to read older formats.
fix
Be aware that backups created with 2025.1.3+ cannot be read by older versions of `securetar`. Plan upgrades carefully to maintain compatibility with your backup/restore processes. Old formats can still be read by newer versions of the library.
affects: >=2025.1.3
breakingThe minimum required Python version was bumped to 3.11 in release 2025.12.0.
fix
Upgrade your Python environment to 3.11 or newer if you are using `securetar` versions 2025.12.0 or later.
affects: >=2025.12.0
gotchaSome earlier versions had potential issues with non-random IVs or padding, which could lead to backup corruption or make decryption less secure. These issues were addressed in later versions, particularly with the introduction of v3.
fix
Ensure you are using the latest `securetar` version (2026.2.0+) for the most robust and secure backup handling. Regenerate existing encryption keys if you suspect past issues.
affects: <2026.2.0
Errors
Common errors & fixes
ReadError: not a gzip file
Attempting to decrypt an encrypted `securetar` archive with an incorrect password, an outdated decryption script, or a version of `securetar` that doesn't support the specific file format (e.g., v3 introduced in 2026.2.0).
fix
Verify the password is correct. Ensure the `securetar` library version used for decryption is compatible with the version used for encryption. If using custom scripts, update them to reflect the latest `securetar` API and file format changes.
Cannot open, not an archive (when using 7-Zip or standard tools)
SecureTar creates a custom encrypted format that is not directly compatible with standard `.tar.gz` or `.zip` tools like 7-Zip for decryption or extraction.
fix
Always use the `securetar` Python library itself for decrypting and extracting contents from a `securetar` archive. Standard archive tools will not recognize the encrypted stream as a valid archive before decryption.
Key derivation failed or 'invalid password' for existing backups after library upgrade.
The key derivation function was moved into the library in version 2025.12.0, causing API changes for how passwords are processed into encryption keys. This can lead to incompatibility with older methods of deriving keys or with backups created using older library versions that processed passwords differently.
fix
Review the API changes in `securetar` versions 2025.12.0 and later. Ensure your application uses the `SecureTarFile` class directly with the password parameter, allowing the library to handle key derivation internally according to the current format specification.
Upgrade
Version history
2026.4.1latest on PyPI · released Apr 7, 2026
Audit
Dependencies
PyNaCloptionalProvides modern cryptographic primitives (XChaCha20-Poly1305) for SecureTar v3, though not a direct PyPI dependency, it's essential for utilizing the latest encryption features.
Agent activity
8 hits · last 30 days
node
6
OpenAI (training)
1
Resources
securetar — pip install securetar · libregistry