CAR Files: How IPFS Packages a DAG Into One File

An IPFS CAR file solves a practical problem this series hasn't addressed yet: how do you actually move a whole DAG, root plus every block underneath it, as a single file, instead of fetching each block separately over the network? CAR (Content Addressable aRchive) is IPFS's answer, a container format that bundles an entire graph of content-addressed blocks together, and it's the same mechanism behind the trustless gateway responses covered earlier in this series.

TL;DR:

• A CAR file packages a DAG, a root CID plus every block reachable from it, into a single portable archive file, similar in spirit to a .tar but built specifically for content-addressed data
• Structurally, a CAR is a header listing one or more root CIDs, followed by a sequence of block records, each pairing a CID with that block's raw bytes
• ipfs dag export writes a CID's entire reachable graph to a CAR file; ipfs dag import reads blocks back in and recursively pins whatever roots the file's header lists
• Because a CAR is just blocks plus their CIDs, importing one doesn't require re-trusting the source, every block can be independently hash-verified against the CID sitting right next to it, the same verification property this series' content-verification article covers
• A CAR file is exactly what the Trustless Gateway spec covered earlier in this series returns when a client requests a ?format=car response, the same archive format used for backup and migration is also what makes gateway responses independently verifiable

The Problem: Moving a Whole DAG At Once

Every retrieval mechanism this series has covered so far, Bitswap's want-have/want-block exchange, a gateway's plain HTTP response, works one request at a time against a live network. That's fine for browsing, but it's the wrong shape for backing up a pinset, migrating content between two IPFS nodes that aren't on the same network, or handing someone an entire dataset as a single downloadable artifact. All of those need the DAG packaged as one self-contained file, not a live sequence of block requests.

The Format: A Header of Roots, Then a Sequence of Blocks

A CAR file has a simple, two-part structure. The header lists one or more root CIDs, the entry points into whatever's packed inside, so a reader knows where to start traversing without needing outside information. After the header comes a sequence of block records, each one a CID paired directly with that block's raw bytes. There's no compression, no fancy indexing beyond that, a CAR is deliberately close to the simplest possible way to serialize "here are some content-addressed blocks and here's where to start."

Exporting: ipfs dag export

Turning a live CID into a CAR file uses ipfs dag export, which walks a CID's entire reachable graph, every block a client would need to fully reconstruct that DAG, and writes the result as a CAR-formatted stream. Redirected to a file, that stream becomes a single, self-contained archive holding everything under that root: for a UnixFS directory, covered earlier in this series, that means every file and subdirectory block underneath it, packaged together.

Importing: ipfs dag import

Going the other direction, ipfs dag import reads a CAR file's blocks into a node's local blockstore, and recursively pins whatever root CIDs the file's own header specifies, the same recursive-pin behavior this series' garbage collection article covers, just triggered by an import instead of a fresh upload. This is what makes a CAR file genuinely portable: handing someone the file is enough for their node to reconstruct and pin the exact same DAG, no live connection to the original source required at any point.

Verification Comes Free, Not Bolted On

Because every block in a CAR sits right next to its own CID, importing one doesn't require trusting whoever handed it over. The same hash-and-compare check this series' content-verification article describes for live retrieval applies identically here: recompute each block's hash, check it against the CID stored alongside it in the archive, and any mismatch is caught locally regardless of how untrusted the file's original source was. A CAR file downloaded from an unfamiliar mirror is exactly as verifiable as one fetched directly from the original uploader.

The Same Format Behind Trustless Gateway Responses

This series' content-verification article already introduced the idea of requesting a CAR response from a gateway instead of a plain pre-resolved file, using the ?format=car parameter or the right Accept header. That's not a separate, gateway-specific format, it's the exact same CAR structure covered here, just delivered live over HTTP instead of saved to disk first. A trustless gateway response and a CAR file exported for backup are the same underlying archive, used in two different contexts.

Where This Fits an AIOZ Pin Workflow

Nothing about exporting a CAR file requires going through AIOZ Pin specifically, since a CAR archive works over any CID on the public IPFS network regardless of who's hosting it. For content pinned on AIOZ Pin, this is the practical mechanism for taking an independent backup or migrating a pinset elsewhere: point ipfs dag export at a pinned CID from any IPFS node with network access to it, and the resulting CAR file is a complete, independently verifiable copy that doesn't depend on AIOZ Pin's infrastructure staying available to remain usable.

Frequently Asked Questions

What is a CAR file in IPFS? A Content Addressable aRchive: a single file packaging a DAG's root CIDs plus every block reachable from them, structured as a header of roots followed by a sequence of CID-and-bytes block records.

How do you create a CAR file from a CID? ipfs dag export <CID> walks the CID's full reachable graph and writes the result as a CAR-formatted stream, which can be redirected to a file.

How do you get content back out of a CAR file? ipfs dag import <file.car> reads the blocks into local storage and recursively pins whatever root CIDs the file's header lists.

Do you have to trust whoever gave you a CAR file? No. Every block sits next to its own CID inside the archive, so each one can be independently hash-verified on import, the same trustless check that applies to any live IPFS retrieval.

Is a CAR file the same thing as a gateway's CAR response? Yes. Requesting ?format=car from a Trustless Gateway returns the exact same archive format described here, delivered over HTTP instead of saved as a standalone file.

Does exporting a CAR file from AIOZ Pin-hosted content require special AIOZ Pin tooling? No. ipfs dag export works over any CID reachable on the public network, including content pinned on AIOZ Pin, using any IPFS node or gateway with access to it.

Related Reading

• How IPFS Verifies Content Without Trusting the Gateway - the Trustless Gateway spec and CAR-response mechanism this article's format is shared with
• What Happens When You Unpin a File on IPFS: Garbage Collection Explained - the same recursive-pin behavior a CAR import triggers
• UnixFS: How IPFS Represents Files and Directories - what actually gets walked and packaged when exporting a directory's DAG
• How AIOZ Pin Actually Keeps Your Files Online: Replication, CIDs, and Proof-of-Storage - the persistence guarantee an independent CAR backup complements
• What Happens to Your Files If You Stop Using AIOZ Pin - the exact scenario a CAR export exists to protect against

References

• IPLD Specs: CAR (Content Addressable aRchive)
• Storacha Docs: Working with CAR Files