Pytorch入门必读：MNIST数据集下载与读取避坑指南

如果你打算入坑Pytorch，MNIST几乎是你绕不开的“人生第一份数据集”。我当初也是照着教程一行行敲，结果第一关就卡了半天——torchvision下载MNIST时给我报了个404，数据没下来，后面全白搭。后来折腾了几轮，把“在线下载”和“本地读取”两条路都走通了，还顺带搞明白了怎么把数据可视化出来。这篇写给准备入门的朋友：两种读取MNIST数据集的方式都会讲到，下载时常见的404问题怎么处理，以及最后怎么用Matplotlib把样本画出来看清楚。

1. 动手前先搞清楚：环境怎么配、数据是什么

1.1 环境准备：先跑通CPU版，再谈GPU

很多小白上来就搜“Pytorch GPU版怎么装”，结果卡在CUDA和显卡驱动上，一搞就是两小时。我的建议是：入门阶段完全可以用CPU版。MNIST单张图片才28×28像素，CPU跑一个最简单的模型，训练一轮也就几十秒到几分钟，完全够用。等你真的把流程跑通了、想上大模型了，再回来研究GPU加速不迟。

安装命令很简单，在终端里执行：

pip install torch torchvision

如果你的网络环境安装比较慢，可以加一个国内PyPI镜像地址，下载速度会快不少：

pip install torch torchvision -i https://pypi.tuna.tsinghua.edu.cn/simple

装完之后，在Python里输入下面几行，能正常打印版本号就说明环境OK：

import torch import torchvision print(torch.__version__) # 例如 2.0.1 print(torchvision.__version__) # 例如 0.15.2

这里我要多提醒一句：torch和torchvision之间的版本是有对应关系的。如果两个库的版本差距太大，在某些老版本里调用datasets.MNIST可能报ImportError或者找不到属性。建议装的时候让pip自动匹配，不要手动指定一个特别老的torch版本再搭最新的torchvision，容易翻车。顺带一提，如果你用的是Anaconda，我更推荐建一个独立环境，比如conda create -n mnist python=3.9，然后再pip装torch，这样不污染你日常用的环境，哪怕后面把环境搞崩了，删掉重建就是。

1.2 MNIST数据集长什么样：28×28的灰度手写数字

MNIST全称是Modified National Institute of Standards and Technology database，简单说就是一批手写数字的黑白扫描图，内容是0到9的阿拉伯数字。整个数据集分成两部分：训练集60000张，测试集10000张。每张图片都是28×28像素，灰度图，像素值范围是0到255，0表示纯黑，255表示纯白，中间是不同程度的灰。

你可能会问：为什么要拿这么简单的一个数据集当入门？原因很直接，数据量小、格式简单、任务明确。60000张28×28的图，放到内存里也就不到50MB，随便一台机器都能跑。任务就是让模型看一张图，说出这是数字几。这个“图像分类”任务虽然简单，但它的处理流程——读取数据、构建批量、送入模型、计算损失、反向传播——和后来做任何深度学习项目完全一样。所以MNIST的价值不在于它本身有多难，而在于它是你理解整套训练流程的最小可行样本。

从数据结构上说，MNIST官方给的原始格式是IDX二进制格式，文件系统里长这样：train-images-idx3-ubyte.gz、train-labels-idx1-ubyte.gz。看着后缀有点唬人，其实本质就是“一个文件里放了很多个图片的像素点，按顺序排好”，再用gzip压缩。你完全可以把它理解成一本按顺序装订好的黑白漫画册，每页是一张28×28的图，旁边写着这页对应的数字标签。至于这个格式具体怎么解析，后面讲“本地读取”时会详细拆。

2. 第一种方式：torchvision在线下载（404问题重点排查）

2.1 datasets.MNIST一行代码下载，参数却大有讲究

torchvision帮我们把MNIST的下载和读取封装好了，最常见的用法是这样：

from torchvision import datasets, transforms transform = transforms.Compose([ transforms.ToTensor(), # PIL图像/ndarray -> Tensor，像素自动归一化到[0,1] ]) train_set = datasets.MNIST( root='./data', # 数据集保存目录，没有会自动创建 train=True, # True取训练集，False取测试集 transform=transform, # 每次取样本时自动执行的预处理 download=True, # 如果root下没有对应文件，自动从网上下载 ) test_set = datasets.MNIST(root='./data', train=False, transform=transform, download=True) print(len(train_set), len(test_set)) # 60000 10000

这里有几个参数值得展开说。

root决定数据落在哪。我建议给一个明确的路径，比如'D:/datasets/mnist'，或者Linux下的'/home/your_name/data/mnist'。刚入门经常有人直接写'./data'，结果换了个命令行目录，跑起来又得重新下载一遍，挺浪费时间的。

download=True的意思是“发现目录里没有对应文件，就启动下载”。如果你已经手动下载好了文件，download=True也不会重新下载，它会先检查文件是否存在，存在就直接读。这个机制后面很有用。

transform=transforms.ToTensor()做的事情有两件：第一，把PIL图像或者numpy数组转成Pytorch的Tensor；第二，把原本0到255的像素值除以255，变成0到1之间的浮点数。这两点非常重要，尤其是归一化。很多模型训练代码里直接拿原始整数像素喂进去，其实也能跑，但收敛效果往往不如归一化好，因为尺度太大容易让梯度更新不稳定。

下载成功之后，root目录下会多出几个文件。你可能以为就是四个.gz，实际torchvision还会在相关目录下建立子目录结构，把raw数据放进去。更关键的是，下次你不加download参数，只把root指对位置，它也能直接读，不用再联网。

2.2 下载报404：原因分析和标准的绕开办法

接下来是重点中的重点，也是很多人实际遇到的情况。首次执行下载时，可能会抛这样的报错：

HTTP Error 404: Not Found

或者：

URLError: <urlopen error [Errno 110] Connection timed out>

很多人刷到“torchvision下载mnist会404”这个话题，可见遇到的不止我一个。这个问题的本质原因是：torchvision内置的MNIST下载地址指向的是国外托管站点的旧链接，在部分网络环境下访问不稳定，连接被重置或者直接返回404。文件本身并没有消失，只是你的网络环境没法稳定访问到这个外部地址。这里不加什么偏门手段，就从开发者的正常思路出发，讲几个标准的解决办法。

解法一：手动下载四个.gz文件，然后离线放置。

MNIST提供的官方文件一共四个：

你可以在任何能访问官方页面的网络环境下（比如单位网络、朋友电脑、手机流量）把这些下载好，传到你的项目目录下。torchvision期望的路径结构是root/MNIST/raw目录下放这四个文件，文件名不能改，gz后缀也不能去。放好后，依然执行datasets.MNIST(root='...', download=True)，它会发现文件齐全，直接跳过下载步骤，进入解压和加载流程。

提示：手动放置时务必保留.gz后缀，文件名不要改动，目录结构必须是 root/MNIST/raw/xxxx.gz，否则torchvision会把文件误判为缺失，重新触发下载。

解法二：覆盖url参数，指向可用的镜像地址。

datasets.MNIST这个类其实暴露了一个url参数，新版本源码里默认值是官方下载地址。如果你手里有内部镜像地址，或者其他能访问的镜像路径，可以直接传进去：

train_set = datasets.MNIST( root='./data', train=True, transform=transform, download=True, url='这里填你自己的镜像地址', )

这个方法最直接，但前提是你得有一个真正可用的镜像地址。我见过不少老教程直接给一个镜像链接，没两天就失效了，所以这里不贴具体域名，你自己找或自己搭都行。判断标准很简单：浏览器能直接打开这个url下载.gz文件，torchvision就能用。

解法三：换一个网络环境，或者错峰重试。

如果是公司网络、校园网络这种出口环境比较特殊的场景，可以试试用手机热点跑下载。我遇到过好几次，电脑上反复超时，切手机热点十几秒就下载成功了。手机热点的网络出口往往和公司、校园网络不同，成功率要高一些。下载中断导致残留的临时文件也别担心，删掉root目录再重新跑就行。

2.3 下载完成后，用DataLoader构建训练批次

torchvision的datasets.MNIST只是一个“数据集容器”，要真正喂给模型，一般还会套一层DataLoader：

from torch.utils.data import DataLoader train_loader = DataLoader( dataset=train_set, batch_size=64, # 每批64张 shuffle=True, # 打乱顺序 num_workers=2, # Windows下填0最稳，Linux下可以开2或4 ) for images, labels in train_loader: print(images.shape) # [64, 1, 28, 28] print(labels.shape) # [64] break

训练时加载器要做两件事：把原始样本按batch拼成一个四维张量，以及按shuffle随机打乱。打乱顺序的好处是避免模型记住固定顺序，比如前三张永远是数字7，后面的永远是数字3，那样训练出来的模型会有偏置。

关于num_workers，Windows系统上经常因为多进程启动方式报错，建议先用0（也就是主进程加载数据），跑通了再考虑加速。

3. 第二种方式：手动下载好文件，完全本地读取

3.1 为什么需要第二种方式

在线下载很方便，但你总会遇到不适合在线下载的场景：比如实验要求全程离线、服务器在内网不能访问外网、又或者你的网络环境连不上官方源。这时候，“本地读取”就派上用场了。其实torchvision内部也是这么干的：download=True只是负责把四个.gz文件拉到本地，之后真正读取数据时，还是走本地解析。所以第二种方式的本质就是“跳过下载这一步，自己动手解析文件”。

3.2 官方文件格式解析：用struct读IDX

先看图像文件train-images-idx3-ubyte.gz。虽然后缀带.gz，但用gzip.open打开后，里面的内容是一个二进制流，最前面是文件头，之后就是连续的像素字节。文件头固定占16字节，按大端序存了4个32位整数：

• 第1个整数：魔数，固定是2051，用来标识“这是一个图像文件”
• 第2个整数：图片数量，训练集是60000
• 第3个整数：行数，28
• 第4个整数：列数，28

读出头之后，剩下的数据就是num乘以rows乘以cols个无符号8位整数（uint8），正好对应每一张28×28图的像素。代码可以这样写：

import gzip import struct import torch import numpy as np def read_idx_images(image_path): with gzip.open(image_path, 'rb') as f: # 按照大端序(>I)读取四个无符号整数 magic, num, rows, cols = struct.unpack('>IIII', f.read(16)) # 剩下的全是像素，按 num*rows*cols 再 reshape raw = np.frombuffer(f.read(), dtype=np.uint8) images = raw.reshape(num, rows, cols).astype(np.float32) / 255.0 return torch.from_numpy(images)

对应的标签文件train-labels-idx1-ubyte.gz结构更简单，文件头只有8字节，两个整数：第一个是魔数2049，第二个是标签数量。之后每个字节是一个标签，取值范围0到9：

def read_idx_labels(label_path): with gzip.open(label_path, 'rb') as f: magic, num = struct.unpack('>II', f.read(8)) raw = np.frombuffer(f.read(), dtype=np.uint8) labels = raw.astype(np.int64) return torch.from_numpy(labels) images = read_idx_images('train-images-idx3-ubyte.gz') labels = read_idx_labels('train-labels-idx1-ubyte.gz') print(images.shape) # torch.Size([60000, 28, 28]) print(labels.shape) # torch.Size([60000]) print(images.min(), images.max()) # tensor(0.) tensor(1.)

有几个地方值得展开解释。

第一，为什么是>IIII？Python的struct默认用本机字节序，也就是小端序，而IDX文件明确规定用大端序。如果忘记加>，读出来的魔数会变成另一个值，最直接的后果是数据全乱。你可以做个实验，把>去掉读一下，立刻会发现数量读成了几百万，整个数组根本没法用。

第二，为什么像素要除以255？这和torchvision的ToTensor做的事情一致。归一化到0到1之后，模型训练时数值稳定性好很多。你如果自己写训练循环，后面加卷积层时，卷积输出的量级也会更正常。

第三，gzip.open返回的是一个文件对象，可以直接f.read()读全部字节。小文件这么读没问题，如果以后处理大文件（比如几十GB的数据集），建议用f.read(chunk_size)分批读，避免一次性占用太多内存。MNIST这点数据量完全无所谓，但养成好习惯没坏处。

3.3 把本地读取封装成标准的Dataset

只是为了拿到数据，直接读成两个Tensor也够用了。但如果你想把它接到训练流程里，最好还是封装成Pytorch官方的Dataset结构，这样DataLoader可以正常调用：

from torch.utils.data import Dataset, DataLoader class MNISTLocalDataset(Dataset): def __init__(self, image_path, label_path): self.images = read_idx_images(image_path) self.labels = read_idx_labels(label_path) def __len__(self): return len(self.images) def __getitem__(self, idx): return self.images[idx], self.labels[idx] train_set_local = MNISTLocalDataset( 'train-images-idx3-ubyte.gz', 'train-labels-idx1-ubyte.gz', )

封装成Dataset之后，配合DataLoader使用的体验和第一种方式完全一致：

train_loader_local = DataLoader(train_set_local, batch_size=64, shuffle=True) for images, labels in train_loader_local: print(images.shape, labels.shape) # torch.Size([64, 28, 28]) torch.Size([64]) break

注意这里images的shape是[64,28,28]，比torchvision给的多了一个批次维度，但少了channel维度。后面如果接卷积层，需要的输入是[N,1,28,28]，加维度的操作很简单：

images = images.unsqueeze(1) # [64, 28, 28] -> [64, 1, 28, 28]

这种“与内置接口不完全一致”其实是常态。深度学习框架给的标准接口通常带着各种假设，比如channel在高维、像素归一化、标签是int64。你的自定义读取只要在喂模型前把这些约定对齐就行。

3.4 两种读取方式的对比与选择

我整理了一个表格，方便你对照：

我的建议是：第一次接触时，两种方式都亲手过一遍。在线方式让你快速看到结果，有成就感；本地方式让你真正理解数据集文件长什么样。以后遇到新数据集，你也不会慌——因为你知道，任何数据集本质上就是“文件 + 格式说明 + 解析代码”三个要素。

4. 可视化MNIST：空口无凭，把图片画出来

4.1 单张图像显示：imshow的几个细节

数据读取成功只是第一步，能看到图才算数。用Matplotlib画单张图很简单：

import matplotlib.pyplot as plt img, label = train_set[0] # 或者 train_set_local[0] print(img.shape) # torch.Size([1, 28, 28]) plt.imshow(img.squeeze(), cmap='gray') plt.title(f'label: {label}') plt.axis('off') plt.show()

这里有三个容易踩的坑。

第一个是squeeze。torchvision的ToTensor会给图像增加一个channel维度，所以单张图shape是[1,28,28]。但Matplotlib的imshow只接受二维矩阵作为灰度图，你不把维度压掉，它会报“Invalid shape”或者画成奇怪的模样。squeeze()会把大小为1的维度去掉，变成[28,28]，正好。

第二个是cmap。原始像素是灰度值，但如果你不指定cmap='gray'，Matplotlib默认用的颜色映射是viridis，也就是绿黄色渐变，乍一看图也能显示，但数字和背景的颜色关系就怪怪的。训练里无所谓，但你做展示图给别人看时，用灰度图最直观。

第三个是坐标轴。axis('off')可以让坐标刻度消失，画面干净很多。如果画在报告里，这一步几乎是必须的。

4.2 九宫格批量预览：随机抽一批样张

单张图只能看个乐，想快速了解数据集，我习惯一次性画3×3或者5×5的网格，随机抽一批样本，并把标签直接打在子图标题里：

import random fig, axes = plt.subplots(3, 3, figsize=(6, 6)) for i, ax in enumerate(axes.flatten()): idx = random.randint(0, len(train_set) - 1) img, label = train_set[idx] ax.imshow(img.squeeze(), cmap='gray') ax.set_title(f'label: {label}', fontsize=12) ax.axis('off') plt.tight_layout() plt.show()

运行之后，你会看到9张手写数字排成3行3列，每张下面标注着它对应的真实标签。这一步看着简单，但特别重要：它实际上在帮你验证“数据读取是否正确”。如果本地的解析代码有bug，比如字节偏移读错，画出来的图很可能就是一片噪点、一团乱线，标签和图形不匹配更是常见。所以每次换一种数据读取方式，我都建议先可视化一批样本再往下走，别急着写训练代码。

另外提一个性能习惯：如果样本量很大，一次别画太多。3×3、5×5就够看清楚了。画100个子图，每个图本身特别小，什么都看不清，反而浪费运行时间。

4.3 把可视化做大一点：看标签分布

从图像本身再往前走一步。MNIST总共10个类别，训练集的标签到底有多均衡？很多人没想过这个问题，其实用Matplotlib画个柱状图3秒就能看出答案：

from collections import Counter labels = [train_set[i][1] for i in range(len(train_set))] counter = Counter(labels) plt.bar(counter.keys(), counter.values()) plt.xlabel('digit') plt.ylabel('count') plt.show()

画出来你会发现，不管是0还是9，各自的样本数量都在5500到7000之间，分布相对均衡。这不算巧合，MNIST本身在设计时就是均匀采集的。做分类任务时，类别均衡有很多好处：不用特别处理样本权重，准确率指标也相对有参考性。

这个思路还可以迁移：以后你拿到任何一个新数据集，第一步都是“看图片长什么样 + 看标签分布均衡不均衡”，这是比模型调参更优先的事情。很多项目前期翻车，不是模型不够好，而是根本没有检查数据读对没有、类别有没有缺漏。

顺带说一句，如果你以后要往数据可视化、数据分析方向走，Matplotlib这套思路也是底子。取数、选图表、调样式、加标签，这套流程在Python数据分析里一通百通。

5. 我踩过的坑和个人使用建议

5.1 下载路径与文件残留：最耗时间的坑

我从头到尾踩过的坑里，最耗时间的是路径问题。刚开始我把root写成'./data'，然后在不同目录下运行脚本，结果每个目录都下了一份，加起来几百MB，乱得不行。第二个坑是下载到一半失败，root目录里留下一堆.tmp或.part文件，重新运行download=True时torchvision误以为有文件，结果又各种报错。最后的解法很粗暴：删掉root整个目录，重新指定一个绝对路径，再跑一次，干干净净。

整理成一张表，方便你排查：

5.2 版本与环境对齐：装环境别贪新

Pytorch版本更新很快，但我不建议一上来就追最新版。如果你是照着某个教程做的，教程里写的是哪个版本的torch和torchvision，你就尽量保持一致，别用2.x的新版本去跑1.x时代的代码，很容易遇到API变化问题。MNIST这种经典数据集还好，datasets.MNIST这些年接口一直稳定，但你后续跟着学模型代码时，版本不匹配的坑会越来越多。稳妥做法是：建独立conda环境，记录下版本号，出了问题可以随时回退。

5.3 下一步可以怎么走

把两种读取方式和可视化都跑通之后，你的下一步其实已经摆在眼前了。最简单的是换数据集——Fashion-MNIST（衣服鞋包分类）和MNIST格式几乎一样，把root改一下，训练代码基本不动，就能体验完全不同的数据分布。再往上走，CIFAR-10是彩色32×32的图，数据结构从二维灰度变成三维RGB，你就需要处理通道维度和归一化的差异。哪怕是以后遇到遥感目标检测数据集、工业设备监测的PHM2012这类完全陌生的数据，处理思路也一模一样：先搞清楚文件格式是什么、标签对应关系是什么，再写一个解析器把它读进来。

如果之后训练自己的模型，我建议把可视化部分封装成一个工具函数，比如show_samples(dataset, rows=3, cols=3)，以后每换一个数据集直接调用，省得来回复制代码。别小看这部分，我自己的经验是：好的数据读取和可视化工具函数，能让你后面整个训练流程省掉一半调试时间。

最后分享一个我实际用下来很顺手的小技巧：每次下载完MNIST，我都会在root目录旁边写一个README.txt，记下“数据下载时间、来源地址、是否可用”三个信息。看起来多余，但过一个月你再打开这个项目时，能省很多回忆的时间。数据读取是深度学习中最小的一件事，恰恰也是每一件事的地基，把这个地基摸熟了，后面的路会顺很多。