Install & Compatibility
Where this runs
tested against v0.0.4 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.049s · 19.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.5s · import 0.043s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pass, Barcode, StoreCard
✓ from wallet.models import Pass, Barcode, StoreCard
✗ import wallet
Directly importing 'wallet' does not expose the necessary models. Always import specific classes from `wallet.models`.
This quickstart demonstrates how to create a simple StoreCard pass. It requires pre-generated `.pem` certificate files and `wwdr.pem`, along with `icon.png` and `logo.png` image assets. The `create` method then generates the `.pkpass` file.
import os
from wallet.models import Pass, Barcode, StoreCard
# --- Prerequisites: Generate .pem files from your Apple Pass Type ID certificate ---
# 1. Obtain a Pass Type ID certificate from Apple's developer portal (.p12).
# 2. Convert it to .pem files using OpenSSL (replace "Certificates.p12" with your file):
# openssl pkcs12 -in "Certificates.p12" -clcerts -nokeys -out certificate.pem
# openssl pkcs12 -in "Certificates.p12" -nocerts -out key.pem -passout pass:YOUR_KEY_PASSWORD
# 3. Download the Apple Worldwide Developer Relations Certification Authority (WWDR) certificate
# from Apple's website (http://developer.apple.com/certificationauthority/AppleWWDRCA.cer)
# and convert it to .pem (e.g., wwdr.pem).
# Ensure these files exist in your working directory or provide full paths.
certificate_path = 'certificate.pem'
key_path = 'key.pem'
wwdr_path = 'wwdr.pem'
key_password = os.environ.get('WALLET_KEY_PASSWORD', 'YOUR_KEY_PASSWORD') # Replace with your actual key password or use env var
# Define pass details
organization_name = 'Your Organization'
pass_type_identifier = 'pass.com.your.organization'
team_identifier = 'AGK5BZEN3E' # Replace with your Apple Team ID
# Create card information
card_info = StoreCard()
card_info.addPrimaryField('name', 'John Doe', 'Name')
card_info.addAuxiliaryField('member_id', '12345', 'Member ID')
# Create the Pass object
passfile = Pass(card_info,
passTypeIdentifier=pass_type_identifier,
organizationName=organization_name,
teamIdentifier=team_identifier)
passfile.serialNumber = '1234567'
passfile.barcode = Barcode(message='Barcode message content', format='PKBarcodeFormatQR')
# Add required assets (icon and logo are mandatory for a valid pass)
# Ensure 'images/icon.png' and 'images/logo.png' exist relative to your script
try:
with open('images/icon.png', 'rb') as f_icon:
passfile.addFile('icon.png', f_icon)
with open('images/logo.png', 'rb') as f_logo:
passfile.addFile('logo.png', f_logo)
except FileNotFoundError:
print("Error: icon.png or logo.png not found. Please create 'images/' directory and place the files.")
exit(1)
output_filename = 'test.pkpass'
# Create and output the Passbook file
try:
passfile.create(
certificate_path,
key_path,
wwdr_path,
key_password,
output_filename
)
print(f"Successfully created {output_filename}")
except Exception as e:
print(f"Error creating pass: {e}")
print("Ensure your .pem files are correct and the key_password is accurate.")
Debug
Known issues
breakingThe library has not been updated since December 2018 and is effectively abandoned. Apple's PassKit requirements and APIs may have evolved, potentially rendering passes generated by this library invalid or incompatible with modern Apple Wallet versions or iOS versions.fixThoroughly test generated passes on current iOS devices. Consider alternative, actively maintained libraries or direct Apple PassKit API interaction if full compatibility is critical.
affects: 0.0.4 and earlier
gotchaGenerating valid `.pem` certificate files from your Apple Developer account `.p12` file is a complex and error-prone process involving `openssl` commands. Incorrectly formatted or expired certificates will lead to pass creation failures.fixCarefully follow the `openssl` commands provided in the quickstart or similar documentation to generate `certificate.pem`, `key.pem`, and `wwdr.pem`. Ensure the `key.pem` is generated with a password, and this password is correctly supplied to the `passfile.create` method.
affects: All
gotchaThe `key.pem` file, generated from your `.p12` certificate, *must* be secured with a password during its creation via `openssl`. Failing to provide a password when prompted by `openssl` will result in an unusable key and subsequent errors during pass signing.fixWhen running `openssl pkcs12 -in "Certificates.p12" -nocerts -out key.pem`, ensure you set a strong password. Then, pass this exact password to the `passfile.create` method via the `key_password` argument.
affects: All
gotchaApple Wallet passes strictly require `icon.png` and `logo.png` files to be included within the pass bundle to be considered valid. Omission of these files will cause the pass to fail validation or display correctly.fixAlways include `icon.png` (29x29pt @1x, @2x, @3x) and `logo.png` (160x50pt @1x, @2x, @3x) using `passfile.addFile('icon.png', open('path/to/icon.png', 'rb'))` and similarly for `logo.png`. affects: All
Errors
Common errors & fixes
Error creating pass: Command '['/usr/bin/zip', '--version']' returned non-zero exit status 1.
This error usually indicates that the `zip` command-line utility, which `wallet-py3k` uses internally, is not found or not executable in the environment where the Python script is run.
fixEnsure that the `zip` utility is installed and available in your system's PATH. On Debian/Ubuntu: `sudo apt-get install zip`. On macOS: `zip` is usually pre-installed. For Windows, you might need to install a `zip` utility or a WSL environment.
Error creating pass: [SSL: BAD_DECRYPT] bad decrypt (_ssl.c:2722)
This error typically means the password provided for the `key.pem` file is incorrect or the `key.pem` itself is corrupted/invalid. This is a common issue during the `passfile.create` step.
fixDouble-check the password passed to `passfile.create`. Verify that `key.pem` was generated with the correct `openssl` command and that you provided a password when it was created. Regenerate `key.pem` and `certificate.pem` if necessary, ensuring to set a password for the key.
Error creating pass: [Errno 2] No such file or directory: 'icon.png'
The `addFile` method for `icon.png` or `logo.png` failed because the specified image file could not be found at the given path.
fixEnsure that the `icon.png` and `logo.png` files exist in the location specified in your `passfile.addFile` calls. If they are in a subdirectory (e.g., 'images/'), make sure that subdirectory exists and contains the files.
AttributeError: module 'wallet' has no attribute 'models'
This happens when you try to import `wallet` directly and then access `wallet.models`. The `models` submodule is not directly exposed this way.
fixAlways import specific classes from `wallet.models` using `from wallet.models import Pass, Barcode, StoreCard`.
Upgrade
Version history
0.0.4latest on PyPI · released Dec 17, 2018
Audit
Dependencies
No dependency data recorded yet.