MNIST Dataset Loader
A uniform, dependency-light interface to MNIST and Fashion-MNIST.
Pure Python + NumPy — no PyTorch, no TensorFlow, no framework lock-in. Download, extract, and load both datasets with a single class.
Features
- Zero framework deps — just
numpyandtqdm. - Automatic download + extraction — fetches from Azure or AWS S3 on first use.
- Two datasets — MNIST handwritten digits and Fashion-MNIST.
- Multiple formats — raw binary (IDX) and ARFF.
- Custom storage — choose where files live.
- Static helpers —
load_images()/load_labels()for low-level access.
Installation
pip install mnist_datasets
Requires Python 3.10+.
Quick start
from mnist_datasets import MNISTLoader
loader = MNISTLoader()
images, labels = loader.load()
# images: (60000, 784) uint8, labels: (60000,) uint8
test_images, test_labels = loader.load(train=False)
# test_images: (10000, 784), test_labels: (10000,)
API
MNISTLoader
| Method | Returns | Description |
|---|---|---|
load(train=True) |
(images, labels) |
Load train (60k) or test (10k) set as NumPy arrays |
load_images(path) |
np.ndarray |
Static — parse raw IDX image file |
load_labels(path) |
np.ndarray |
Static — parse raw IDX label file |
from_arff(train=True) |
(images, labels) |
Static — load from OpenML ARFF format |
Constructor
MNISTLoader(
dataset_type="default", # "default" or "fashion"
base_url=None, # override the download URL
folder=None, # storage directory (defaults to cwd)
)
Examples
Fashion-MNIST
loader = MNISTLoader('fashion')
images, labels = loader.load()
Custom directory
loader = MNISTLoader(folder='/tmp/mnist_data')
ARFF format (educational)
images, labels = MNISTLoader.from_arff(train=False)
This is extremely slow — included for understanding the data format.
Verify ARFF vs binary consistency
import numpy as np
arff_imgs, arff_lbls = MNISTLoader.from_arff(train=False)
bin_imgs, bin_lbls = MNISTLoader().load(train=False)
np.alltrue(arff_imgs == bin_imgs), np.alltrue(arff_lbls == bin_lbls)
Low-level parsing
images = MNISTLoader.load_images('/tmp/t10k-images-idx3-ubyte')
labels = MNISTLoader.load_labels('/tmp/t10k-labels-idx1-ubyte')
Dataset file format
Image file (*-images-idx3-ubyte)
| Offset | Content | Value |
|---|---|---|
| 0–3 | Magic number | 2051 (0x803) |
| 4–7 | Number of images | 60,000 / 10,000 |
| 8–11 | Rows | 28 |
| 12–15 | Columns | 28 |
| 16+ | Pixel data | 0–255 per pixel |
Label file (*-labels-idx1-ubyte)
| Offset | Content | Value |
|---|---|---|
| 0–3 | Magic number | 2049 (0x801) |
| 4–7 | Number of labels | 60,000 / 10,000 |
| 8+ | Label data | 0–9 per byte |
Project structure
| Path | Purpose |
|---|---|
mnist_datasets/loader.py |
MNISTLoader class |
mnist_datasets/__init__.py |
Public API exports |
train.py |
PyTorch training example |
mnist.ipynb |
Jupyter notebook demo |
setup.py |
PyPI packaging |
License
MIT. See LICENSE.
Metadata
Release files for mnist-datasets 0.15
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mnist_datasets-0.15.tar.gz | 6.1 kB | Without provenance | Details for mnist_datasets-0.15.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mnist_datasets-0.15-py3-none-any.whl | Python 3 | none | any | Details for mnist_datasets-0.15-py3-none-any.whl |
Total release size: 12.7 kB
Release files / mnist_datasets-0.15.tar.gz
| Download URL | mnist_datasets-0.15.tar.gz |
|---|---|
| Size | 6.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1368d16d60dfcd1ad92e183ba6d5c5abdc7ae2bd51b9b068a0e0aec58e8bd62e
|
|
BLAKE2b-256 checksum How to use checksums |
545b8411d0648a50578dde5ebde1c548db96a145dfd3227e435b456797634781
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / mnist_datasets-0.15-py3-none-any.whl
| Download URL | mnist_datasets-0.15-py3-none-any.whl |
|---|---|
| Size | 6.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1487bdff25a6c2284fc57fd4108d1c7950501257decd8a987659528c438bc8f1
|
|
BLAKE2b-256 checksum How to use checksums |
c87001d3025c4e9f978ab0cbcafefcc35a31d717e60f9dd172202aa909e93c5b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for mnist-datasets 0.15
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.