Install & Compatibility
Where this runs
tested against v1.8.0 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 25.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.4s · import 0.000s · 26MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BDBag
✓ from bdbag import BDBag
✗ from bdbag import BDBag
bdbag
✓ import bdbag
✗ from bdbag import BDBag
This quickstart demonstrates how to create a simple bdbag, add a data file to it, and then validate its integrity. It sets up a temporary directory, writes a small file, and uses `bdbag_api.make_bag` to create the bag and `bdbag_api.validate_bag` to check its validity.
import os
import shutil
from bdbag import bdbag_api
# Define paths for the bag
bag_dir = "my_test_bag"
data_dir = os.path.join(bag_dir, "data")
test_file_path = os.path.join(data_dir, "example.txt")
# Clean up previous run if directory exists
if os.path.exists(bag_dir):
shutil.rmtree(bag_dir)
# 1. Create data directory for the bag payload
os.makedirs(data_dir, exist_ok=True)
# 2. Create some data to put into the bag
with open(test_file_path, "w") as f:
f.write("This is some example data for the bdbag.\n")
f.write("It will be bagged and validated.\n")
print(f"Created test data at: {test_file_path}")
try:
# 3. Create the bag
# The data_directory argument tells bdbag where to find the payload files
# and move/link them into the bag's 'data' directory.
bag = bdbag_api.make_bag(bag_dir,
checksum_algorithms=['sha256'],
data_directory=data_dir)
print(f"Bag created successfully at: {bag.path}")
# 4. Validate the bag
is_valid = bdbag_api.validate_bag(bag_dir)
if is_valid:
print(f"Bag '{bag_dir}' is valid.")
else:
print(f"Bag '{bag_dir}' is NOT valid. Check logs for details.")
except Exception as e:
print(f"An error occurred during bag creation or validation: {e}")
finally:
# Optional: Clean up the created bag directory
# Uncomment the line below to remove the directory after inspection
# if os.path.exists(bag_dir):
# shutil.rmtree(bag_dir)
pass
bdbag --version
Debug
Known issues
gotchabdbag strictly enforces Python version compatibility. It requires Python versions 3.8 through 3.11. Using it with unsupported versions (e.g., Python 3.7 or Python 3.12+) can lead to `ImportError`, `ModuleNotFoundError`, or unexpected runtime errors due to dependency conflicts or syntax incompatibilities.fixEnsure your Python environment is within the supported range (3.8-3.11). Use virtual environments (e.g., `venv` or `conda`) to manage specific Python versions for your projects.
affects: <1.8.0,>=3.8,<3.12
gotchaWhen creating a bag, if you provide a `data_directory` argument to `bdbag_api.make_bag`, bdbag expects this directory to contain the actual data files you want to include. It will then manage moving/linking these files into the bag's internal `data/` directory. If `data_directory` is omitted, `bdbag_api.make_bag` creates an empty bag, and you'll need to manually add files using `bag.add_file()` or similar methods.fixFor creating bags with existing data, always specify the `data_directory` argument pointing to the source of your payload data. For empty bags, omit `data_directory` and use bag manipulation methods.
affects: >=1.0.0
gotchaBy default, `bdbag` uses SHA256 checksums for payload files if `checksum_algorithms` is not specified during bag creation. If you need specific checksum algorithms (e.g., MD5, SHA1), always explicitly pass them as a list to the `checksum_algorithms` parameter in `bdbag_api.make_bag`.fixAlways specify `checksum_algorithms=['md5', 'sha256']` (or your preferred list) when calling `bdbag_api.make_bag` if the default SHA256 is not sufficient or you need multiple algorithms.
affects: >=1.0.0
Upgrade
Version history
1.8.0latest on PyPI · released Sep 29, 2025
Audit
Dependencies
bagitrequiredCore dependency for implementing the BagIt specification.
requestsrequiredUsed for fetching remote manifests and data payloads.
h5pyrequiredRequired for HDF5 data handling features.