What Is a .pkpass File? (And How to Open, Create and Distribute One)

A .pkpass file is the file format Apple Wallet uses to store and display a pass — a boarding pass, loyalty card, event ticket, coupon or membership card on your iPhone or Apple Watch. If you have ever added a pass to Apple Wallet by tapping a link or opening an email attachment, you have already interacted with a .pkpass file without necessarily knowing what it was.

Understanding the format is useful whether you are building a wallet pass integration, debugging a pass that is not behaving correctly or simply curious about how the technology works. This guide explains exactly what is inside a .pkpass file, how the signing mechanism works and how to create and distribute one.

What a .pkpass File Actually Is

A .pkpass file is a ZIP archive — the same compression format used by .zip files — renamed with a .pkpass extension. If you rename a .pkpass file to .zip and extract it, you will find a folder of ordinary files. Apple Wallet reads this bundle of files and uses them to render the pass.

The .pkpass extension triggers Apple's operating system to open the file with the Wallet app rather than a file manager or archive utility. On a Mac, the Finder knows to open .pkpass files with the Wallet preview. The file format itself is just a ZIP.

What Is Inside a .pkpass File

A valid .pkpass bundle contains the following files:

• pass.json — the core data file. Contains all the pass fields, design configuration, pass type, barcode data and organisation details. This is the file you edit when you want to change what the pass displays.
• manifest.json — a JSON object listing every other file in the bundle alongside its SHA1 hash. Apple Wallet verifies these hashes on load to confirm the bundle has not been tampered with.
• signature — a PKCS7 detached digital signature of the manifest.json file. This is the cryptographic proof that the pass was created by an authorised party. Without a valid signature, Apple Wallet will reject the pass entirely.
• icon.png — the small icon displayed in Wallet's pass list view, at 29x29 points (58x58 pixels for retina).
• logo.png — the organisation logo displayed in the header of the pass.
• strip.png — an optional background strip image displayed on store card and coupon pass types.
• background.png — an optional full-bleed background image used on event ticket pass types.
• thumbnail.png — an optional small image displayed on certain pass types, such as a product image on a coupon.
• footer.png — an optional image used on some pass types near the barcode.

Each image must also have a @2x retina variant (e.g. icon@2x.png). All images are listed in the manifest.json and hashed.

The pass.json Structure

The pass.json file is the heart of the bundle. A minimal valid pass.json looks like this in structure:

• passTypeIdentifier — a reverse-domain string identifying the pass type, e.g. pass.com.yourcompany.loyalty. This must match a pass type you have registered in your Apple Developer account.
• teamIdentifier — your 10-character Apple Developer Team ID, found in the developer portal.
• serialNumber — a unique string identifying this specific pass instance. Two passes with the same passTypeIdentifier and serialNumber are considered the same pass — issuing one will replace the other.
• organizationName — the name displayed at the top of the pass header.
• description — a human-readable description of the pass, used for accessibility.
• formatVersion — always 1 for the current Apple Wallet format.
• barcode — an object containing the message (the QR code content), the format (PKBarcodeFormatQR, PKBarcodeFormatPDF417, etc.) and an optional altText displayed below the barcode.
• Pass type object — one of: boardingPass, coupon, eventTicket, generic or storeCard. Each contains a primaryFields, secondaryFields, auxiliaryFields and backFields array specifying the data fields to display.

Each field object in a fields array has at minimum a key (machine-readable identifier), a label (displayed above the value) and a value (the displayed content). Fields can include date formatting, number formatting and change message properties for push update notifications.

How Signing Works

The signature file is what makes a .pkpass trustworthy. Without it, or with an invalid signature, Apple Wallet will refuse to add the pass.

The signing process works as follows. First, you create the manifest.json by computing a SHA1 hash of every file in the bundle (pass.json, all images). Second, you sign the manifest.json using your pass certificate — a P12 file obtained from your Apple Developer account after registering a pass type — using PKCS7 signing with a detached signature. The resulting signature file is placed in the bundle alongside the manifest.json.

When a device receives the .pkpass file, Apple Wallet verifies the signature against Apple's certificate authority chain, confirms the pass type identifier matches the certificate and checks that all file hashes in the manifest match the actual files. Any tampering — modifying pass.json after signing, swapping an image — invalidates the signature and the pass is rejected.

This is why signing cannot be skipped and why certificate management is one of the more operationally demanding parts of building a wallet pass system yourself. Pass certificates expire annually. An expired certificate means any passes you issue after expiry will be rejected, and updating existing passes will fail.

How to Open a .pkpass File

On iPhone or iPad: tap any .pkpass file — in an email, a website link or a message — and Apple Wallet opens automatically, showing a preview of the pass. Tap "Add to Wallet" to save it.

On Mac: double-click the .pkpass file. The system opens it in a Wallet preview showing the pass face. This does not add it to Wallet on the Mac but lets you inspect the design.

On Windows or Android: .pkpass files cannot be added to Apple Wallet from a non-Apple device. On Windows, there are third-party pass viewer apps and online tools (such as PassSource Pass Viewer) that let you inspect the contents. On Android, .pkpass files are not natively supported — Android devices use Google Wallet passes, which use a different format and distribution mechanism.

How to Create a .pkpass File

There are two approaches: manual and platform-based.

Manually: write your pass.json, prepare your images, run a manifest generation script that computes SHA1 hashes, sign the manifest using your P12 certificate with an OpenSSL command, and ZIP the resulting bundle as a .pkpass file. This requires an Apple Developer account, a registered pass type, a pass certificate and a working OpenSSL setup. It is doable for a developer but tedious to productionise.

Via a platform: use Issuepass to create a template in the visual editor, fill in your pass data and let us handle certificate management, signing, manifest generation and hosting. No JSON editing, no OpenSSL commands, no certificate renewal reminders. Start free and have a valid, distributable .pkpass file in minutes.

How to Distribute a .pkpass File

HTTPS URL: host the .pkpass file at an HTTPS URL and serve it with the MIME type application/vnd.apple.pkpass. When a user on iPhone taps the link, Apple Wallet opens automatically. This is the standard distribution method.

QR code: generate a QR code pointing to the HTTPS pass URL. Print it on marketing materials, display it on a screen at an event, or embed it in a web page. Scanning the QR code on iPhone opens Apple Wallet.

Email: link to the pass URL in the email body — do not attach the .pkpass file directly. Gmail and some other email clients strip .pkpass attachments as a security measure. A clearly labelled "Add to Apple Wallet" button linking to the hosted URL is the reliable approach.

SMS: include the pass URL in an SMS message. Tapping the link on iPhone prompts the user to add the pass to Wallet.

Issuepass generates a unique hosted pass URL for every pass you issue. Distribution is handled — share the link however works for your workflow.