Skip to main content

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 numpy and tqdm.
  • 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)

Source distribution for mnist-datasets 0.15
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)

Table of built distributions (wheels) for mnist-datasets 0.15
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page