How to format converter for linux & container engineers
- Step 1Identify what your pipeline ingests — Most Linux/container steps want
.tar.gz. Confirm the target format your job expects before converting — that is what you will set in the dropdown (it defaults to tar.gz). - Step 2Drop the incoming artifact — Drag the partner's ZIP / 7z / rar / gz onto archive-format-converter. The tool detects the real format from magic bytes, so the extension does not have to be honest.
- Step 3Set targetFormat to tar.gz — Leave
targetFormatat its defaulttar.gzfor the standard case. Pickziponly if a downstream Windows step needs it, orgzfor a single-file payload. - Step 4Convert and download — Run the conversion. The tool decompresses every entry and rebuilds a TAR, then GZIPs it at level 6. The download is named from the input stem (e.g.
chart.zip→chart.tar.gz). - Step 5Re-apply metadata in CI if needed — Because mode resets to 0644 and timestamps reset, if your image needs executables or stable mtimes, fix them in the Dockerfile/CI (
chmod,--mtime) after extraction, or normalize timestamps with timestamp-normalizer. - Step 6Verify before it hits the registry — Confirm the entry tree and integrity with file-listing-generator and archive-integrity-tester so a bad partner drop fails on your desk, not in the deploy.
Conversion paths a container engineer actually uses
All paths preserve the entry tree; metadata caveats apply to every TAR.GZ/ZIP output.
| Incoming | Set targetFormat | Output | Engine path |
|---|---|---|---|
Partner .zip | tar.gz (default) | .tar.gz for the pipeline | fflate read + manual TAR + gzip |
Vendor .7z | tar.gz | .tar.gz | libarchive WASM read + gzip |
Vendor .rar | tar.gz | .tar.gz | libarchive WASM read + gzip |
.xz / .tar.xz | tar.gz | .tar.gz | libarchive WASM read + gzip |
.tar.gz for a Windows step | zip | .zip | fflate read + zipSync |
Single-file .zip | gz | .gz | fflate read + gzipSync |
What survives conversion (container-relevant)
Critical for anyone packing rootfs or layer content — this tool is content-faithful but metadata-lossy.
| Attribute | Survives? | Implication for images |
|---|---|---|
| Directory / file tree | Yes | Paths and nesting are exact |
| File contents (bytes) | Yes | Bit-for-bit content preserved |
| Unix mode / exec bit | No (reset to 0644) | Re-chmod entrypoints/scripts after extract |
| Timestamps (mtime) | No (set to now) | Use --mtime or timestamp-normalizer for reproducible layers |
| Symlinks / hardlinks | No (flattened) | Re-create links in the Dockerfile |
| Ownership (uid/gid) | No | Set with --numeric-owner / chown in build |
Cookbook
Real container-engineering conversions. Blocks show the incoming artifact, the dropdown choice, and what your pipeline gets.
Windows partner ZIP → TAR.GZ for the build job
Your CI ADDs a .tar.gz of vendored assets. The partner sends ZIP. One conversion fixes it.
Incoming: partner-assets.zip targetFormat: tar.gz (default) Output: partner-assets.tar.gz CI step: ADD partner-assets.tar.gz /opt/assets/ Reminder: chmod +x any scripts after ADD — mode is 0644.
Vendor .7z → TAR.GZ without p7zip
Hardened workstation, no p7zip allowed. libarchive WASM reads the 7z in-browser.
Incoming: firmware-blobs.7z targetFormat: tar.gz libarchive WASM extracts → manual TAR → gzip level 6 Output: firmware-blobs.tar.gz (Source: 7z, Target: TAR.GZ)
Helm chart .zip from a UI export → TAR.GZ
Some chart UIs export ZIP; helm wants .tgz. Convert, then rename to .tgz.
Incoming: mychart.zip targetFormat: tar.gz Output: mychart.tar.gz → rename to mychart.tgz helm install myrel ./mychart.tgz
Multi-file → GZIP is the wrong call
GZIP is single-stream; a layer with many files must be tar.gz.
Incoming: rootfs.zip (412 files) targetFormat: gz Result: Error — GZIP target supports a single file only. Fix: targetFormat: tar.gz
Reproducible layer: normalize after convert
The converter stamps mtime=now, which breaks layer caching reproducibility. Normalize timestamps as a follow-up.
Incoming: assets.zip → convert → assets.tar.gz (mtime = now) Follow-up: run timestamp-normalizer on assets.tar.gz targetTimestamp: 1980-01-01 Result: deterministic mtimes for stable layer hashes.
Edge cases and what actually happens
Executable bit lost on entrypoint scripts
By designOutput entries default to mode 0644 and ZIP carries no Unix mode field, so a +x script comes out non-executable. Re-apply with chmod +x in the Dockerfile/CI after extraction, or pack the rootfs with tar --mode in your build instead.
Layer hashes change every convert (timestamps)
Not preservedThe TAR builder stamps mtime with the current time, so two converts of the same input produce different bytes and break layer caching. Run timestamp-normalizer on the output for reproducible layers.
Symlinks in a rootfs drop
FlattenedSymlinks and hardlinks become regular files in the output because ZIP has no link concept and the rebuilt TAR writes regular-file headers. Re-create links in your build steps.
Encrypted vendor 7z / rar
Rejectedlibarchive WASM cannot accept passwords and this tool has no password field, so encrypted 7z/rar fail. Decrypt locally with 7-Zip/WinRAR, then convert the plaintext archive.
Fat artifact over the tier cap
Over limitFree caps at 50 MB / 500 entries. A multi-hundred-MB base layer or a tree with thousands of files needs Pro (500 MB / 50,000) or Pro-media/Developer (2 GB / 500,000). Check both size and entry count.
GZIP target on a multi-file layer
RejectedGZIP holds one stream. A layer with multiple files must use tar.gz. The tool throws 'GZIP target supports a single file only' if you pick gz for multi-entry input.
Helm expects .tgz, you got .tar.gz
Cosmetic.tgz and .tar.gz are the same format; only the extension differs. Rename after download. The bytes are a valid gzipped TAR either way.
WebAssembly disabled by workstation policy
Engine error7z/rar/bz2/xz reads need libarchive WASM. If policy blocks WASM, those inputs fail; ZIP/GZIP/TAR/TAR.GZ still convert via fflate. Check the browser console for the WASM worker error.
Frequently asked questions
Why is TAR.GZ the default target?
Because Linux and container tooling overwhelmingly expects .tar.gz — base-image sources, Helm bundles and release artifacts. The default targetFormat: tar.gz makes the most common conversion a single drag with no dropdown change.
Can I convert a vendor 7z without installing p7zip?
Yes. libarchive WASM reads 7z (and rar, bz2, xz, iso) entirely in the browser, so you get a clean TAR.GZ or ZIP out without adding p7zip/unrar to a hardened workstation.
Is this safe for confidential partner archives?
The conversion is 100% browser-side with no upload — the archive is read into memory in your tab and repacked locally. There is no server endpoint, which is usually far easier to clear with security than an external service or unvetted CLI.
Will it preserve my Unix permissions for a rootfs layer?
No. Output mode defaults to 0644 and ZIP has no mode field. This tool is for getting content into the right container, not for permission-sensitive layers. Re-chmod in the build, or pack the layer with tar in CI.
Does it break reproducible builds?
It can — the TAR builder stamps the current time as each entry's mtime, so output bytes change per run. Normalize with timestamp-normalizer (e.g. to 1980-01-01) for deterministic layer hashes.
Can it output a native 7z or xz layer?
No — it writes only ZIP, TAR.GZ and GZIP. For native 7z/xz use the CLI in your build. The closest portable output here is TAR.GZ.
What compression level does it use?
A fixed level 6 (DEFLATE/GZIP). There is no level control on this tool. For tuning, run compression-level-optimizer on the converted file.
What happens to symlinks in the artifact?
They are flattened to regular files because ZIP cannot represent them and the rebuilt TAR writes regular-file headers. Re-create symlinks in your Dockerfile after extraction.
Can I batch-convert a whole directory of vendor drops?
Not in one run — the converter takes one archive at a time. For scripted nightly batch conversion, use the CLI; for in-browser batch UNPACKING, see batch-extraction-manager.
Why did my GZIP conversion fail?
GZIP is single-stream, so a multi-file archive cannot become .gz. Pick tar.gz instead. The gz target only works when the input has exactly one entry.
Helm wants .tgz but I got .tar.gz — is that a problem?
No. .tgz is just an alias for .tar.gz; rename the download and helm will accept it. The byte format is identical.
What size limits apply to artifacts?
Free: 50 MB and 500 entries. Pro: 500 MB and 50,000 entries. Pro-media and Developer: 2 GB and 500,000 entries. Both the size and entry-count caps apply per archive.
Privacy first
Every JAD Archive tool runs entirely in your browser using fflate, @zip.js/zip.js, and the libarchive WASM bridge. Your archives never leave your device — verified by zero outbound network requests during processing.