> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dev/miniprem/nvidia-drivers.md).

# NVIDIA ドライバー

**ドライバー要件:** ミニプレム（MiniPrem）では NVIDIA プロプライエタリドライバーのバージョン 580.82.x または 580.142 が必要です。オープンソースの `nouveau` ドライバーはサポートされておらず、バージョン 580.126.x はすべての GPU タイプで NVENC エンコーディングが破損します。

MiniPrem では、正しいプロプライエタリドライバーがインストールされた動作する NVIDIA GPU が必要です。本ページでは、ドライバーの種類、プロプライエタリドライバーが必要な理由、インストール方法および検証手順について解説します。

{% hint style="warning" %}
前提条件を満たす環境の準備はお客様の責任において実施いただきますようお願いいたします。デジタルヒューマン株式会社では前提条件を満たすための環境構築のサポート、ドライバー等の不具合に対する対応作業は提供しておりません。
{% endhint %}

{% hint style="warning" %}
2026年6月現在、デジタルヒューマン株式会社の正式サポート対象はデフォルト（Default Install）の Renny のみです。フルインストール（Full Install）に含まれる Renny 以外のサービス（vLLM、Flowise、RIME AI、NVIDIA RIVA、Whisper など）はサポート対象外です。
{% endhint %}

## クイックリファレンス

| ドライバー                           | MiniPrem で動作するか | 備考                                     |
| ------------------------------- | --------------- | -------------------------------------- |
| **nouveau**（オープンソース）            | 不可              | CUDA、NVENC、Vulkan のいずれにも対応しません。動作しません。 |
| **NVIDIA プロプライエタリ < 580**       | 不可              | 必須となる Vulkan および NVENC 機能が欠落しています。     |
| **NVIDIA プロプライエタリ 580.82.x**    | 可 推奨            | すべてのデプロイメントで推奨されるバージョンです。              |
| **NVIDIA プロプライエタリ 580.142**     | 可               | サポート対象バージョンです。                         |
| **NVIDIA プロプライエタリ 580.126.x**   | 不可              | すべての GPU タイプで NVENC が破損します。            |
| **NVIDIA プロプライエタリ 580 以降**（その他） | 場合による           | 本番環境にデプロイする前に NVENC をテストしてください。        |

**警告:** オープンソースの `nouveau` ドライバーは CUDA、NVENC、Vulkan の**いずれにも対応していません**。nouveau がインストールされた状態では MiniPrem は動作しません。公式の NVIDIA プロプライエタリドライバーを使用してください。

## 推奨バージョン

### Docker / ベアメタル デプロイメント

| バージョン         | インストール方法                  | 推奨用途                                      |
| ------------- | ------------------------- | ----------------------------------------- |
| **580.82.07** | apt（Ubuntu パッケージマネージャー）   | 大半のデプロイメント（L4、A10G、T4）                    |
| **580.82.09** | .run インストーラー（NVIDIA 直接配布） | 新しい GPU アーキテクチャ（Blackwell / RTX PRO 6000） |
| **580.142**   | apt または .run              | サポート対象バージョン                               |

### Kubernetes デプロイメント

NVIDIA GPU Operator がドライバーのインストールを自動で処理します。デフォルトでドライバーバージョン 580 以降がインストールされます。GPU Operator の構成詳細については、[AWS EKS デプロイメント](/dev/miniprem/kubernetes-overview/kubernetes-eks.md) または [Azure AKS デプロイメント](/dev/miniprem/kubernetes-overview/kubernetes-aks.md) のガイドを参照してください。

### 避けるべきバージョン

**580.126.x — 使用しないでください:** このバージョンは**すべての** GPU タイプ（L4、A10G、T4、RTX）で NVENC ハードウェアエンコーディングが破損します。セッションは接続されますが、Pixel Streaming が映像フレームをエンコードできないため即座に失敗します。580.82.x にダウングレードしてください。

## ドライバーの種類

### nouveau（オープンソース）

`nouveau` は NVIDIA GPU 向けにリバースエンジニアリングされたオープンソースドライバーです。大半の Linux ディストリビューションにデフォルトで同梱されています。基本的な画面出力は提供しますが、以下の機能を欠いています。

* CUDA コンピュート対応
* NVENC / NVDEC ハードウェアエンコード / デコード
* Vulkan グラフィックス API 対応
* 最新世代カードにおける適切な GPU 電力管理

nouveau は MiniPrem と**互換性がありません**。

### NVIDIA プロプライエタリドライバー

公式の NVIDIA プロプライエタリドライバーは、CUDA、NVENC、Vulkan を含むフル機能の GPU 機能を提供します。MiniPrem ではこのドライバーの**バージョン 580 以降**が必要です。

## Vulkan とは

Vulkan は低オーバーヘッドのクロスプラットフォーム**グラフィックス API** であり、ドライバーそのものではありません。NVIDIA プロプライエタリドライバーのバージョン 580 以降には Vulkan サポートが含まれており、以下の用途で必要となります。

* **Ada Lovelace GPU**（RTX 4000 シリーズ、L4、L40）
* **Blackwell GPU**（RTX 5000 シリーズ、B100、B200）
* Renny で使用される Unreal Engine 5 の Pixel Streaming

古いバージョンのプロプライエタリドライバーでは、これらの GPU アーキテクチャに必要な Vulkan 機能が不足している場合があります。

## OS 要件

**OS 要件:** MiniPrem には **Ubuntu 24.04 LTS 以降**（ネイティブインストール）が必要です。WSL（Windows Subsystem for Linux）は**サポート対象外**です。GPU パススルー、Docker ネットワーキング、ドライバー互換性に関する問題を引き起こします。

## バージョン要件（CUDA / Chrome）

NVIDIA ドライバーとあわせて、以下のソフトウェアバージョンを満たしている必要があります。

| ソフトウェア                   | 要件                | 補足                                                |
| ------------------------ | ----------------- | ------------------------------------------------- |
| **CUDA**                 | 12.2 以降（13.0 使用可） | Renny 起動失敗の典型原因がバージョンずれのため、`nvcc -V` で必ず確認してください。 |
| **Google Chrome**（表示端末側） | 124 以降            | 表示端末側のブラウザバージョンが古いと WebRTC 通信が成立しないことがあります。       |

{% hint style="info" %}
推奨スペック・apt 必須パッケージ・事前診断スクリプトなど、NVIDIA ドライバー以外の前提条件の詳細は [前提条件ガイド](/dev/miniprem/prerequisites.md) を参照してください。\
ファイアウォール許可リスト・WebRTC 用 UDP ポート範囲などのネットワーク要件は [ネットワーク要件ガイド](/dev/miniprem/network-requirements.md) を参照してください。
{% endhint %}

## Secure Boot と事前準備

NVIDIA プロプライエタリドライバーを Ubuntu 24.04 上にインストールする際は、以下の事前準備を整えた上でインストール作業を進めてください。

### Secure Boot の無効化または MOK 署名

{% hint style="warning" %}
**Secure Boot 有効時の注意:** Secure Boot（UEFI のセキュアブート）が有効な状態では、NVIDIA のカーネルモジュールがロードされず、`nvidia-smi` が動作しないケースが頻発します。日本国内で流通する Dell / HP / Lenovo の BTO ワークステーション・サーバーは Secure Boot が初期状態で有効になっていることが多いため、ドライバーインストール前に必ず以下のいずれかで対処してください。\
\
・BIOS / UEFI 設定画面（起動時に `DEL` / `F2` / `F12` 等）から Secure Boot を無効化する\
・Secure Boot を無効化できない運用ポリシーの場合は、MOK（Machine Owner Key）でカーネルモジュールに署名する
{% endhint %}

`sudo modprobe nvidia` を実行した際に次のメッセージが表示された場合、Secure Boot による NVIDIA モジュール拒否が原因です。

```bash
ERROR: could not insert 'nvidia': Key was rejected by service
```

カーネル更新時にも署名が再チェックされるため、カーネルアップグレード後に再びドライバーが読み込まれなくなる場合があります。運用ポリシーに従って Secure Boot を無効化したままにするか、MOK 署名運用へ切り替えてください。

### kernel-headers / dkms / build-essential の事前導入

NVIDIA ドライバーは DKMS（Dynamic Kernel Module Support）でカーネルに対してビルドされます。ドライバーインストール前に、以下のパッケージを必ず導入してください。

```bash
# Install kernel headers, DKMS, and build tools before NVIDIA driver
sudo apt update
sudo apt install -y linux-headers-$(uname -r) dkms build-essential
```

{% hint style="info" %}
カーネルヘッダーが未導入のままドライバーをインストールすると、ビルド時に `unable to locate kernel headers` 等のエラーが発生し、再起動後に `nvidia-smi` が `NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver` を返す原因となります。
{% endhint %}

### CUDA Toolkit インストール時の注意

CUDA Toolkit パッケージには NVIDIA ドライバーが同梱されており、CUDA リポジトリから `cuda-toolkit-<version>` をインストールすると、既存ドライバーが上書きされる場合があります。

推奨ワークフローは以下のとおりです。

1. まず推奨ドライバー（例: `nvidia-driver-580`）を単独でインストールし、`nvidia-smi` で動作確認する
2. その後、CUDA Toolkit を追加でインストールし、互換性を確認する

## インストール方法

### 方法 1: ubuntu-drivers ユーティリティ（推奨）

Ubuntu において最もシンプルなアプローチです。

```bash
# Update package lists
sudo apt update

# List available NVIDIA drivers
ubuntu-drivers devices

# Install the recommended driver (ensure version is 580+)
sudo ubuntu-drivers install nvidia:580

# Reboot to load the new driver
sudo reboot
```

### 方法 2: NVIDIA サイトからのダウンロード

NVIDIA から `.run` インストーラーを直接ダウンロードします。

1. [NVIDIA ドライバーダウンロード](https://www.nvidia.com/Download/index.aspx) にアクセスします
2. GPU モデル、オペレーティングシステム（Linux 64-bit）を選択し、ダウンロードします
3. インストールを実行します。

```bash
# Stop the display manager
sudo systemctl stop gdm3

# Make the installer executable and run it
chmod +x NVIDIA-Linux-x86_64-580*.run
sudo ./NVIDIA-Linux-x86_64-580*.run

# Reboot
sudo reboot
```

### 方法 3: CUDA Toolkit（ドライバー同梱）

CUDA toolkit のインストーラーには互換性のある NVIDIA ドライバーが同梱されています。

```bash
# Add NVIDIA CUDA repository
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update

# Install CUDA toolkit (includes driver 580+)
sudo apt install cuda

# Reboot
sudo reboot
```

CUDA 12.4 を明示的にインストールする場合は、以下のコマンドでインストールしたうえで、`PATH` と `LD_LIBRARY_PATH` の環境変数を設定してください。

```bash
# Install CUDA Toolkit 12.4 explicitly
sudo apt install -y cuda-toolkit-12-4

# Add CUDA paths to ~/.bashrc
echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc

# Apply changes
source ~/.bashrc

# Verify
nvidia-smi
nvcc -V
```

{% hint style="info" %}
環境変数を設定せずに `nvcc -V` を実行すると `command not found` となるため、`~/.bashrc` への追記と `source ~/.bashrc` を忘れずに実行してください。
{% endhint %}

## 検証

インストール完了後、ドライバーが動作していることを確認します。

```bash
# Check driver version and GPU status
nvidia-smi
```

期待される出力（580.82.x が表示され、580.126.x ではないことを確認してください）。

```
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.82.07    Driver Version: 580.82.07    CUDA Version: 12.8               |
|-----------------------------------------------------------------------------------------+
| GPU  Name        Persistence-M | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|=========================================================================================|
|   0  NVIDIA L4             Off | 00000000:00:1E.0 Off |                    0 |
| N/A   35C    P8     9W /  72W |      0MiB / 23034MiB |      0%      Default |
+-----------------------------------------------------------------------------------------+
```

**ヒント:** `nvidia-smi` が `NVIDIA-SMI has failed` と表示するか、command-not-found エラーを返す場合、プロプライエタリドライバーがインストールされていません。nouveau がロードされていないか確認してください: `lsmod | grep nouveau`。ロードされている場合はブラックリストに追加し、プロプライエタリドライバーをインストールしてください。

## nouveau のブラックリスト化

nouveau がロードされている場合、NVIDIA プロプライエタリドライバーをインストールする前にブラックリストに追加してください。

```bash
# Create blacklist file
sudo bash -c 'echo -e "blacklist nouveau\noptions nouveau modeset=0" > /etc/modprobe.d/blacklist-nouveau.conf'

# Regenerate initramfs
sudo update-initramfs -u

# Reboot
sudo reboot
```

再起動後、nouveau がロードされていないことを確認します。

```bash
lsmod | grep nouveau
# Should return nothing
```

その後、上記のいずれかのインストール方法を実行します。

## トラブルシューティング

| 症状                                                | 想定される原因                               | 対処方法                                                          |
| ------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------- |
| `nvidia-smi` が見つからない                              | ドライバー未インストール                          | プロプライエタリドライバーをインストール（上記参照）                                    |
| `NVIDIA-SMI has failed`                           | ドライバー / カーネル不一致                       | ドライバーを再インストールし、再起動                                            |
| `modprobe nvidia` で `Key was rejected by service` | Secure Boot 有効によるカーネルモジュール拒否          | [Secure Boot の無効化または MOK 署名](#secure-boot-の無効化または-mok-署名) を参照 |
| `lsmod` 出力に `nouveau` が含まれる                       | オープンソースドライバーがロード済み                    | nouveau をブラックリスト化（上記参照）                                       |
| Renny ログに NVENC エラー                               | ドライバーバージョンが古すぎる                       | 580.82.x にアップグレード                                             |
| Pixel Streaming が黒画面                              | Vulkan サポート不足                         | プロプライエタリ 580.82.x にアップグレード                                    |
| セッション接続後すぐに切断                                     | NVENC が破損（580.126.x）                  | 580.82.x にダウングレード                                             |
| アクティブセッション中に `nvidia-smi dmon` で `enc: 0%`        | NVENC が破損（580.126.x）                  | 580.82.x にダウングレード                                             |
| `nvcc -V` が `command not found`                   | CUDA の `PATH` / `LD_LIBRARY_PATH` 未設定 | [方法 3: CUDA Toolkit](#方法-3-cuda-toolkitドライバー同梱) の環境変数設定を実行    |

追加のサポートについては、[MiniPrem トラブルシューティングガイド](/dev/miniprem/troubleshooting.md) を参照してください。