1. 為什么 PyTorch 安裝這件事值得單獨寫一篇如果你已經(jīng)裝過三四次 PyTorch可能會覺得這話題沒什么好聊的——一條命令的事。但我在過去幾年幫人排查環(huán)境問題的經(jīng)歷里遇到最多的恰恰不是模型不收斂、不是顯存爆了而是裝完之后import torch直接報錯或者更隱蔽的裝上了、能跑但 GPU 用不了代碼默默跑在 CPU 上訓練一晚上發(fā)現(xiàn)進度條幾乎沒動。PyTorch 的安裝之所以容易出問題根源在于它的分發(fā)形態(tài)和普通 Python 包不一樣。它不是一個純 Python 包而是Python 接口 編譯好的 C/CUDA 后端二進制的組合體。你pip install torch拿到的 wheel 文件里打包了針對特定 CUDA 版本、特定操作系統(tǒng)、特定 Python 版本編譯好的動態(tài)庫。這四個維度Python 版本、操作系統(tǒng)、CUDA 版本、PyTorch 版本只要有一個對不上就會出現(xiàn)各種奇怪的報錯。更麻煩的是網(wǎng)上流傳的安裝教程大量過期。很多文章還在教你pip install torch1.7.0或者給一個早就失效的下載鏈接。而 PyTorch 官方從 2.x 開始安裝命令的生成邏輯、CUDA 版本的支持矩陣都變了好幾輪。你照著三年前的教程操作大概率會卡在某個環(huán)節(jié)。這篇內(nèi)容面向的是這樣幾類人第一次裝 PyTorch 完全不知道從哪下手的新手裝過但被環(huán)境問題折磨過、想搞清楚背后邏輯的進階用戶以及需要在多臺機器、多個項目之間維護不同 PyTorch 版本的人。我會把安裝這件事拆成選版本、裝環(huán)境、驗證、排錯四個環(huán)節(jié)每個環(huán)節(jié)都講清楚為什么這么做而不只是給命令。命令你復制粘貼就行但只有理解了邏輯下次遇到新情況才能自己判斷。先給一個核心結(jié)論PyTorch 安裝的正確姿勢是先確定你的硬件和驅(qū)動能力再反推該裝哪個 CUDA 版本的 PyTorch最后用官方生成的命令安裝裝完必須做一次完整的驗證。順序反了就會反復重裝。2. 裝之前必須搞清楚的三個版本關(guān)系很多人裝 PyTorch 失敗是因為一上來就打開搜索引擎搜pytorch安裝教程然后照著第一條結(jié)果敲命令。正確的做法是先花五分鐘搞清楚自己機器上的版本約束這五分鐘能省下后面兩小時的折騰。2.1 顯卡驅(qū)動版本決定了你能用的 CUDA 上限如果你用的是 NVIDIA 顯卡第一件事是打開命令行執(zhí)行nvidia-smi這個命令會輸出一個表格右上角有一行CUDA Version: 12.4之類的信息。注意這個數(shù)字不是你已經(jīng)安裝的 CUDA 版本而是你的驅(qū)動所能支持的最高 CUDA 版本。這是最容易誤解的一點。很多人看到這里顯示 12.4就以為自己裝的是 CUDA 12.4其實系統(tǒng)里可能一個 CUDA Toolkit 都沒裝。這個上限值很關(guān)鍵。假設你的驅(qū)動支持到 CUDA 12.1那你就不能裝需要 CUDA 12.4 的 PyTorch 版本否則運行時會報CUDA driver version is insufficient for CUDA runtime version。反過來驅(qū)動支持 12.4你裝 CUDA 11.8 版本的 PyTorch 是完全可以的向下兼容沒問題。如果你的nvidia-smi命令直接報不是內(nèi)部或外部命令說明驅(qū)動沒裝或者沒加到 PATH。這時候先去 NVIDIA 官網(wǎng)下載對應顯卡型號的驅(qū)動裝上再回來繼續(xù)。2.2 PyTorch 自帶的 CUDA 運行時不需要你單獨裝 CUDA Toolkit這是第二個高頻誤解。很多人以為要用 GPU 版 PyTorch必須先去 NVIDIA 官網(wǎng)下載安裝幾個 GB 的 CUDA Toolkit。實際上不需要。PyTorch 的 pip 和 conda 包已經(jīng)把所需的 CUDA 運行時庫打包進去了你裝完 PyTorch 就能直接用 GPU。那什么時候需要單獨裝 CUDA Toolkit只有當你需要編譯自定義的 CUDA 算子、或者用某些需要調(diào)用nvcc的庫比如某些版本的 DeepSpeed、apex時才需要。對于絕大多數(shù)訓練和推理場景PyTorch 自帶的運行時足夠了。這個設計的好處是省事壞處是每個 PyTorch 版本綁定了特定的 CUDA 版本你沒法自由組合。比如 PyTorch 2.1 的官方 wheel 提供 cu118 和 cu121 兩個版本你想要 cu120 就沒有。所以選 PyTorch 版本時要看你驅(qū)動支持的上限能不能覆蓋它綁定的 CUDA 版本。2.3 Python 版本和 PyTorch 版本的對應關(guān)系PyTorch 每個版本對 Python 的支持范圍是有限的。比如 PyTorch 2.0 支持 Python 3.8 到 3.11PyTorch 2.4 支持 Python 3.8 到 3.12。如果你用的是 Python 3.13那可能只有最新的 PyTorch 版本才支持。這里有個實用建議不要用系統(tǒng)自帶的 Python也不要用最新版的 Python。系統(tǒng)自帶的 Python尤其是 Linux 上的往往被系統(tǒng)工具依賴你往里裝包可能搞壞系統(tǒng)。最新版 Python 則可能還沒被 PyTorch 官方支持。穩(wěn)妥的選擇是用 conda 或 venv 創(chuàng)建一個獨立環(huán)境Python 版本選 3.10 或 3.11這兩個版本目前兼容性最好幾乎所有主流的深度學習庫都支持。把這三個關(guān)系理清楚你就能確定自己要裝哪個組合了。下面給一個決策表你的情況推薦做法有 NVIDIA 顯卡驅(qū)動較新裝 GPU 版CUDA 版本選驅(qū)動支持上限以下的有 NVIDIA 顯卡驅(qū)動很舊先升級驅(qū)動或裝較老的 PyTorch 版本只有核顯或 AMD 顯卡裝 CPU 版或考慮 ROCm 版僅 Linux蘋果 M 系列芯片裝默認版MPS 加速已內(nèi)置不確定先裝 CPU 版跑通流程再換 GPU 版3. 環(huán)境隔離conda 和 venv 到底選哪個環(huán)境隔離這件事新手容易忽略老手容易過度糾結(jié)。我的觀點很明確如果你已經(jīng)在用 conda就繼續(xù)用 conda如果沒用過直接用 venv 就夠了。不要為了裝 PyTorch 專門去學 conda。3.1 conda 的優(yōu)勢和它的坑conda 最大的優(yōu)勢是它能管理非 Python 的依賴比如 CUDA 運行時、MKL 數(shù)學庫這些。用 conda 裝 PyTorch 時它會自動幫你解決這些底層庫的版本匹配問題。對于不熟悉系統(tǒng)依賴的用戶這省了不少事。但 conda 也有幾個坑。第一是下載慢默認的 channel 在國內(nèi)訪問速度堪憂需要配置鏡像源。第二是環(huán)境體積大一個裝了 PyTorch 的 conda 環(huán)境動輒幾個 GB。第三是conda 和 pip 混用容易出問題如果你先用 conda 裝了 PyTorch又用 pip 裝了某個依賴可能導致依賴沖突。還有一個高頻問題conda activate命令報無法將 conda 項識別。這通常是因為 conda 沒有初始化 shell。解決辦法是執(zhí)行conda init然后重啟終端。Windows 上如果用的是 PowerShell可能還需要調(diào)整執(zhí)行策略。3.2 venv 的輕量和它的局限venv 是 Python 標準庫自帶的不需要額外安裝創(chuàng)建環(huán)境就是一條命令python -m venv pytorch_env激活方式因系統(tǒng)而異Windows 是pytorch_env\Scripts\activateLinux 和 macOS 是source pytorch_env/bin/activate。venv 的優(yōu)點是輕量、干凈、和 pip 配合完美。缺點是它只管 Python 包不管系統(tǒng)級的庫。不過前面說了PyTorch 的 wheel 已經(jīng)把 CUDA 運行時打包進去了所以這個缺點在裝 PyTorch 這個場景下基本不影響。3.3 我的實際選擇我自己在本地開發(fā)時用 venv因為快、干凈。在服務器上做多項目隔離時用 conda因為需要管理不同項目的 CUDA 版本。如果你只是想在本地跑通 PyTorchvenv 完全夠用而且少一層抽象出問題更容易排查。創(chuàng)建好環(huán)境后記得先升級 pippython -m pip install --upgrade pip這一步很多人跳過但老版本的 pip 在解析 PyTorch 這種大包的依賴時可能出問題升級一下能避免一些莫名其妙的錯誤。4. 拿到正確的安裝命令官方生成器怎么用PyTorch 官網(wǎng)有一個安裝命令生成器這是最可靠的來源。但很多人不會用或者用了但沒注意細節(jié)。4.1 生成器的選項怎么選打開官網(wǎng)的安裝頁面你會看到幾個下拉框PyTorch Build選 Stable穩(wěn)定版。Preview 是預覽版除非你要用某個剛出的新特性否則別選。Your OS選你的操作系統(tǒng)。Package選 pip 或 conda。前面說了我推薦 pip。Language選 Python。Compute Platform這是最關(guān)鍵的一項。CUDA 11.8、CUDA 12.1、CUDA 12.4 這些是 GPU 版本CPU 是純 CPU 版本ROCm 是 AMD 顯卡用的。選 Compute Platform 時對照你nvidia-smi看到的驅(qū)動上限。比如驅(qū)動支持到 12.4那 CUDA 12.1 和 11.8 都可以選。選哪個選較新的那個因為新版本通常有性能優(yōu)化和新特性支持。但如果你的項目依賴某個只支持舊 CUDA 的庫那就選舊的。生成出來的命令大概長這樣pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121注意那個--index-url參數(shù)它指定了從 PyTorch 自己的包索引下載而不是從 PyPI。這是因為 PyPI 上的 torch 包默認是 CPU 版本或者在某些時期是特定 CUDA 版本要裝特定 CUDA 版本必須指定索引。4.2 國內(nèi)下載慢怎么辦PyTorch 的官方索引在國內(nèi)訪問速度不穩(wěn)定幾個 GB 的包下載可能要很久還容易斷。這時候可以用國內(nèi)的鏡像源。常用的有清華源、阿里源等。但這里有個坑鏡像源同步 PyTorch 的 CUDA 版本包可能不全。有些鏡像只同步了 CPU 版本你指定 cu121 的索引它找不到。所以用鏡像時先確認它有沒有你要的版本。如果鏡像不全可以試試用鏡像下載 CPU 版先跑通流程或者用一些支持斷點續(xù)傳的工具下載 wheel 文件再本地安裝。本地安裝 wheel 的命令是pip install torch-2.4.0cu121-cp311-cp311-linux_x86_64.whlwheel 文件名里的cp311表示 Python 3.11linux_x86_64表示平臺。下載時要選對選錯了裝不上。4.3 一個容易被忽略的細節(jié)torchvision 和 torchaudio 的版本匹配安裝命令里通常一起裝了 torch、torchvision、torchaudio 三個包。這三個包的版本是嚴格對應的不能隨便混搭。比如 torch 2.4.0 對應 torchvision 0.19.0、torchaudio 2.4.0。如果你單獨升級了其中一個可能導致 import 時報錯。用官方生成的命令一起裝就不會有這個問題。如果你需要單獨裝某個版本去 PyTorch 官網(wǎng)的版本對應表查一下別憑感覺裝。5. 裝完之后的驗證不止是 import torch裝完 PyTorch 后很多人就敲一句import torch看沒報錯就完事了。這遠遠不夠。import torch成功只說明 Python 能找到這個包不代表 CUDA 可用、不代表能正常計算。完整的驗證要分幾層做。5.1 第一層基礎導入和版本確認import torch print(torch.__version__) print(torch.version.cuda)第一行輸出 PyTorch 版本比如2.4.0cu121。注意那個cu121后綴它明確告訴你這是 CUDA 12.1 版本。如果你裝的是 CPU 版這里不會有cu后綴。第二行輸出 PyTorch 編譯時用的 CUDA 版本。如果輸出None說明你裝的是 CPU 版。如果輸出一個版本號說明是 GPU 版。這兩行能幫你確認裝的是不是你想要的那個版本。我見過有人以為自己裝了 GPU 版結(jié)果torch.version.cuda輸出 None白折騰半天。5.2 第二層CUDA 是否真的可用print(torch.cuda.is_available()) print(torch.cuda.device_count()) print(torch.cuda.get_device_name(0))is_available()返回 True 才算 GPU 可用。如果返回 False即使你裝的是 GPU 版也用不了。常見原因有幾個驅(qū)動版本太低、顯卡太老不支持當前 CUDA、或者系統(tǒng)里有多個 CUDA 版本沖突。device_count()返回可見的 GPU 數(shù)量。如果你有多張卡但這里只顯示一張可能是CUDA_VISIBLE_DEVICES環(huán)境變量限制了。get_device_name(0)返回第一張卡的型號確認一下是不是你預期的那張。5.3 第三層實際跑一次 GPU 計算前面兩步都是查詢狀態(tài)真正要驗證的是能不能在 GPU 上做計算。跑一段最小代碼import torch # 創(chuàng)建一個張量并移到 GPU x torch.randn(1000, 1000).cuda() y torch.randn(1000, 1000).cuda() # 做一次矩陣乘法 z torch.matmul(x, y) # 把結(jié)果移回 CPU 并打印 print(z.sum().item()) print(z.device)這段代碼做了三件事在 GPU 上創(chuàng)建張量、在 GPU 上做矩陣乘法、把結(jié)果移回 CPU。如果全部跑通且z.device輸出cuda:0說明 GPU 計算鏈路是通的。為什么要在 GPU 上做矩陣乘法而不是簡單加法因為矩陣乘法會調(diào)用 cuBLAS 庫能驗證 CUDA 的數(shù)學庫是否正常工作。加法可能只用到最基礎的 kernel驗證不夠充分。5.4 第四層驗證反向傳播如果你要用 PyTorch 訓練模型還得驗證自動求導在 GPU 上是否正常import torch x torch.randn(10, 10, requires_gradTrue, devicecuda) y (x ** 2).sum() y.backward() print(x.grad.device) print(x.grad.shape)這段代碼驗證了 GPU 上的反向傳播。如果x.grad能正常計算出來且 device 是 cuda說明訓練所需的核心功能都正常。5.5 一個完整的驗證腳本把上面幾層整合成一個腳本每次裝完新環(huán)境跑一遍import torch def verify_pytorch(): print(fPyTorch version: {torch.__version__}) print(fCUDA version: {torch.version.cuda}) print(fCUDA available: {torch.cuda.is_available()}) if torch.cuda.is_available(): print(fDevice count: {torch.cuda.device_count()}) print(fDevice name: {torch.cuda.get_device_name(0)}) # GPU 計算測試 x torch.randn(1000, 1000, devicecuda) y torch.randn(1000, 1000, devicecuda) z torch.matmul(x, y) print(fMatmul result device: {z.device}) # 反向傳播測試 a torch.randn(10, 10, requires_gradTrue, devicecuda) b (a ** 2).sum() b.backward() print(fGradient device: {a.grad.device}) print(All GPU checks passed.) else: print(CUDA not available, running on CPU only.) if __name__ __main__: verify_pytorch()這個腳本我放在每個新環(huán)境的根目錄裝完就跑一次幾秒鐘的事能省下后面大量排查時間。6. 那些年我踩過的安裝坑和排查思路前面講的是正確流程但現(xiàn)實中你更可能遇到的是已經(jīng)出問題了怎么辦。這一節(jié)我把遇到過的典型問題和排查鏈路整理出來你可以對照自己的報錯找線索。6.1 報錯 CUDA driver version is insufficient這個報錯的意思是你裝的 PyTorch 需要的 CUDA 運行時版本高于你驅(qū)動支持的版本。比如你裝了 cu121 的 PyTorch但驅(qū)動只支持到 CUDA 11.8。排查步驟先nvidia-smi看驅(qū)動支持的 CUDA 上限再python -c import torch; print(torch.version.cuda)看 PyTorch 需要的版本。如果前者小于后者就是這個問題。解決辦法有兩個升級顯卡驅(qū)動或者重裝一個低 CUDA 版本的 PyTorch。升級驅(qū)動通常更簡單去 NVIDIA 官網(wǎng)下載對應型號的最新驅(qū)動裝上就行。但如果是服務器升級驅(qū)動可能需要重啟要挑個合適的時間。6.2 報錯 ImportError: libcudart.so.11.0: cannot open shared object file這是 Linux 上常見的問題說明系統(tǒng)找不到 CUDA 運行時庫?？赡艿脑騊yTorch 裝的是 GPU 版但系統(tǒng)里沒有對應的 CUDA 庫而 PyTorch 又沒能用自帶的。等等前面不是說 PyTorch 自帶 CUDA 運行時嗎是的但有些情況下它會去系統(tǒng)路徑找。比如你用 conda 裝的時候conda 可能裝了一個系統(tǒng)級的 CUDA 庫然后 PyTorch 去鏈接它結(jié)果版本對不上。排查方法ldd命令查看 torch 的動態(tài)庫依賴ldd $(python -c import torch; print(torch.__file__)) | grep cuda如果看到某些 cuda 庫顯示 not found就是這個問題。解決辦法通常是重裝 PyTorch確保用 pip 而不是 conda或者清理掉系統(tǒng)里沖突的 CUDA 庫。6.3 裝完 import 很慢或者卡住有時候import torch要等十幾秒甚至更久。這通常不是安裝問題而是 PyTorch 在初始化時掃描 CUDA 設備、加載庫。如果機器上有多個 CUDA 版本或者網(wǎng)絡文件系統(tǒng)慢會更明顯。一個緩解辦法是設置環(huán)境變量CUDA_MODULE_LOADINGLAZY讓 CUDA 模塊延遲加載。另一個辦法是確認沒有多個 CUDA 版本在 PATH 里打架。如果 import 直接卡死不動可能是顯卡驅(qū)動和 PyTorch 版本不兼容或者有其他進程占用了 GPU。先nvidia-smi看看有沒有僵尸進程占著顯存。6.4 Windows 上的特有問題Windows 上裝 PyTorch 有幾個額外的坑。第一是路徑里有中文或空格可能導致某些庫加載失敗。建議把 Python 環(huán)境和項目都放在純英文、無空格的路徑下。第二是多個 Python 版本共存。Windows 上可能同時裝了 Python 3.9、3.10、3.11你pip install裝到了 A 版本但運行時用的是 B 版本。解決辦法是用python -m pip install而不是直接pip install確保裝到當前python對應的環(huán)境里。第三是驅(qū)動簽名問題。有些情況下 Windows 會攔截未簽名的驅(qū)動導致 GPU 不可用。這個在正規(guī)渠道下載的 NVIDIA 驅(qū)動上很少見但如果遇到了需要調(diào)整系統(tǒng)的驅(qū)動簽名策略。6.5 排查問題的通用思路遇到任何安裝問題按這個順序排查確認版本python --version、pip --version、nvidia-smi、torch.__version__把四個版本都打出來。確認環(huán)境which pythonLinux或where pythonWindows確認你操作的是哪個 Python。確認安裝位置python -c import torch; print(torch.__file__)看 torch 是從哪加載的?？赐暾麍箦e不要只看最后一行往上翻通常真正的錯誤信息在前面。搜索報錯關(guān)鍵詞把報錯的核心句子去掉路徑和變量名拿去搜通常能找到遇到同樣問題的人。這個順序的核心邏輯是先確認事實再猜測原因。很多人一看到報錯就開始瞎試試了半小時才發(fā)現(xiàn)自己一直在錯誤的 Python 環(huán)境里操作。7. 多版本共存和項目隔離的實戰(zhàn)建議如果你同時維護多個項目它們可能依賴不同版本的 PyTorch。這時候怎么管理7.1 一個項目一個環(huán)境最穩(wěn)妥的做法是每個項目一個獨立環(huán)境。用 venv 的話cd project_a python -m venv .venv source .venv/bin/activate # Linux/macOS pip install torch2.1.0 cd ../project_b python -m venv .venv source .venv/bin/activate pip install torch2.4.0每個項目的依賴記錄在requirements.txt里換機器時重建環(huán)境就行。這個做法看起來笨但最不容易出問題。7.2 用 requirements.txt 鎖定版本requirements.txt里不要只寫torch要寫具體版本torch2.4.0 torchvision0.19.0 torchaudio2.4.0如果用了 CUDA 特定版本還要在安裝時指定索引?？梢栽?requirements 文件里加一行--index-url https://download.pytorch.org/whl/cu121 torch2.4.0這樣pip install -r requirements.txt就會從正確的索引裝正確的版本。7.3 導出和復現(xiàn)環(huán)境裝好一個能用的環(huán)境后導出完整依賴列表pip freeze requirements_lock.txt這個文件記錄了所有包的精確版本包括間接依賴。換機器時用這個文件重建能最大程度復現(xiàn)原環(huán)境。注意pip freeze會導出所有包包括你不需要的可以手動清理一下。7.4 關(guān)于 Docker 的一點建議如果你的項目要部署到服務器或者需要嚴格的環(huán)境一致性用 Docker 是最省心的。PyTorch 官方提供了各種版本的鏡像直接FROM pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime就行。Docker 的好處是環(huán)境完全隔離不會和宿主機沖突。壞處是需要 GPU 支持時要裝 nvidia-container-toolkit多一層配置。如果你只是本地開發(fā)用 venv 就夠了如果要部署Docker 值得投入時間學一下。8. 驗證通過之后下一步做什么裝完、驗證通過只是萬里長征第一步。接下來你大概率要做這幾件事我順帶說幾個容易踩的點。第一件事是確認你的數(shù)據(jù)能正常加載到 GPU。很多人驗證時用的是隨機張量真到加載數(shù)據(jù)集時發(fā)現(xiàn) DataLoader 的num_workers設置不對或者 pin_memory 沒開導致 GPU 利用率上不去。這些是性能問題不是安裝問題但裝完就該順手檢查。第二件事是確認混合精度訓練能用。如果你打算用torch.cuda.amp裝完可以跑個小例子驗證一下from torch.cuda.amp import autocast, GradScaler scaler GradScaler() with autocast(): # 你的前向計算 pass如果這里報錯可能是 PyTorch 版本和 CUDA 版本不匹配或者顯卡太老不支持。第三件事是記錄下你的環(huán)境信息。把torch.__version__、torch.version.cuda、nvidia-smi的輸出存一份以后出問題時對比用。我習慣在項目根目錄放一個env_info.txt記錄這些信息團隊協(xié)作時特別有用。最后分享一個我自己的習慣每次裝完新環(huán)境除了跑驗證腳本我還會跑一個最小的訓練循環(huán)用真實的數(shù)據(jù)集比如 MNIST訓練幾個 epoch確認整個鏈路——數(shù)據(jù)加載、前向、反向、優(yōu)化器更新、驗證——都正常。這個測試大概兩分鐘但能發(fā)現(xiàn)很多import torch發(fā)現(xiàn)不了的問題。裝環(huán)境這件事多花十分鐘驗證能省下后面幾小時的排查。