2026.07.19 データベース

DuckDBの使い方：インストールからPython・CLI・ファイル読み込みまでの実装手順

DuckDBはpip install duckdbやbrew install duckdbの1コマンドで導入でき、サーバーを立てずにSQLでParquet・CSV・JSONを直接集計できるインプロセス型の分析エンジンです。本記事では、Windows・macOS・Python環境ごとのインストール手順、CLIの基本操作、ファイル読み込みと書き出し、pandasとの連携までを実行コマンド付きで解説します。対象は2026年7月時点の安定版である1.5系（公式表記 Version 1.5.4）です。最後に、どのデータ規模・体制ならDuckDBを採用してよいか、どこからクラウドDWHに切り替えるべきかの判断基準も言い切ります。

目次

まとめ：DuckDBは3コマンドで動く。ローカル分析はまずこれで足りる

導入はWindowsがwinget install DuckDB.cli、macOSがbrew install duckdb、Pythonがpip install duckdb。この3系統いずれかで数分あれば動きます。起動後はSELECT * FROM 'sales.parquet'のようにファイル名をそのままテーブルとして参照でき、事前のスキーマ定義もインポート作業も不要です。

使いどころの結論は明快です。1人〜少人数が単一マシンで完結させるデータ分析・ETL前処理・ファイル形式変換ならDuckDBを第一候補にしてよく、逆に複数プロセスからの同時書き込みが発生する業務システムのバックエンドや、部署横断で権限管理が要る全社共有基盤には合いません。その線引きの根拠と、超えた場合の移行先は本文後半の判断章で具体的に示します。

DuckDBの実行モデルと適用範囲：インプロセス分析基盤という前提

手を動かす前に、DuckDBが「どこで動くDBなのか」だけ押さえておくと、後続の手順の意味が分かりやすくなります。

インプロセスで動く列指向OLAPエンジンという位置づけと他DBとの役割差

DuckDBはアプリケーションのプロセス内に組み込まれて動くOLAP（分析処理）特化のデータベースで、PostgreSQLのような常駐サーバーを持ちません。SQLiteのアーキテクチャを分析向けに置き換えた存在と捉えると近く、行単位の更新に強いSQLiteに対し、DuckDBは列指向ストレージとベクトル化実行で集計・結合を高速に処理します。ライセンスはMITで、商用利用でも費用は発生しません。定義や他DBとの比較の詳細はDuckDBとは？特徴・用途とSQLite・PostgreSQLとの違いを解説で扱っているため、本記事は手順に集中します。

単一ノードで完結するデータ分析・ETL前処理という適用範囲の目安

適用範囲の目安は「1台のマシンに載るデータを、1人または少人数で分析する」場面です。具体的には、数百MB〜数十GB規模のCSV・Parquetの集計、BIに渡す前の前処理、ログの形式変換が代表例になります。1.5系時点の公式ドキュメントは、メモリに収まらないデータを一時ファイルへ退避しながら処理する動作（out-of-core処理)にも言及しており、メモリ8GB程度のノートPCでも数十GB級の集計が現実的です。サーバー管理者がいない部門でも導入できる点が、クラウドDWHとの最初の分かれ目になります。ブラウザ内でDuckDBを動かすWebAssembly版の仕組みと制約はDuckDB WASMとは？ブラウザでSQL分析を実行する仕組みと実装・採用判断で扱っています。

DuckDBのインストール手順：Windows・macOS・Python環境別の導入

導入経路はCLI（コマンドライン）とPythonライブラリの2系統です。分析をSQL中心で進めるならCLI、既存のPythonワークフローに組み込むならライブラリを選びます。両方入れても干渉しません。

Windowsへの導入手順：wingetコマンドと再頒布パッケージの注意点

Windowsでは、PowerShellからwinget install DuckDB.cliを実行するのが公式案内の手順です。インストール後にduckdb --versionでバージョン番号が返れば完了になります。つまずきやすいのは実行時にDLL不足のエラーが出るケースで、公式サイトはMicrosoft Visual C++ Redistributableの導入が必要になる場合があると注記しています。エラーメッセージにvcruntimeの文字が含まれていたら、Microsoftの配布ページから再頒布パッケージを入れて再実行してください。企業の管理端末でwingetが使えない場合は、公式サイトのZIP配布版を展開してPATHを通す方法でも動きます。

macOS・Linuxへの導入：Homebrewとインストールスクリプト

macOSはHomebrewでbrew install duckdbの1行です。LinuxはOSのパッケージマネージャーを経由せず、公式サイト（duckdb.org）が案内するインストールスクリプトをシェルで実行する方式が案内されており、ホームディレクトリ配下に単一バイナリが置かれます。どちらの環境でも、依存ミドルウェアの追加は不要です。単一バイナリで完結する配布形態のため、CI環境や使い捨てのコンテナに入れる場合もイメージ肥大化がほぼ起きません。バージョン固定が必要な本番バッチでは、公式GitHubのリリースページから特定バージョンのバイナリを直接取得する運びが安全です。

Python環境への導入：pip installと動作確認の手順

pip install duckdbで導入し、import duckdbが通れば準備完了です。condaを使うチームはconda-forgeチャンネルからも取得できます。動作確認は対話シェルでduckdb.sql('SELECT 42').show()を実行し、結果表が表示されるかを見るのが最短です。注意点は、CLIとPythonライブラリのバージョンが独立していることです。DuckDBの永続化ファイルはバージョン間で互換性が保たれる設計ですが、新機能を使う場合は両者を揃えておくと切り分けが楽になります。requirements.txtにはduckdb==1.5.4のようにバージョンを固定し、更新は意図的に行う運用を推奨します。

DuckDB CLIの基本操作：インメモリ実行と永続データベースの使い分け

CLIは試行錯誤の主戦場です。起動方法の違いと、知っておくと効率が変わるドットコマンドに絞って説明します。

インメモリ実行とデータベースファイル永続化を切り替える起動方法

引数なしでduckdbと打つとインメモリモードで起動し、作成したテーブルは終了と同時に消えます。使い捨ての集計やファイル変換はこちらで十分です。結果を残したい場合はduckdb analytics.duckdbのようにファイル名を渡すと、そのファイルに永続化された状態で起動します。拡張子に決まりはなく、.duckdbや.dbが慣例です。永続化ファイルは後述のPythonクライアントからも同じパス指定で開けるため、「CLIで探索し、確定したクエリをPythonの定期処理へ移す」という流れが自然に組めます。同一ファイルへ書き込めるプロセスは同時に1つという制約だけ覚えておいてください。

ドットコマンドと出力モード変更：.tables・.mode markdownの操作

CLI内ではSQLに加えてドットコマンドが使えます。実務で頻用するのは次の4つです。

  • .tables：現在のデータベース内のテーブル一覧を表示
  • .mode markdown：結果表をMarkdown形式で出力（議事録・ドキュメント貼り付けに直結）
  • .read query.sql：SQLファイルを一括実行（定型処理の再現に使う）
  • .quit：終了

出力モードは既定のduckbox形式のほかcsvやjsonにも切り替えられ、.mode csvにしてから実行すればリダイレクトでそのままCSVが作れます。調査結果をチームに共有する場面では、markdownモードの出力をそのままプルリクエストやWikiに貼れるのが地味に効きます。

Parquet・CSV・JSONの読み込みと書き出し：ファイル直接クエリの実装

DuckDBの中心的な使い方がファイルの直接クエリです。ロード工程を挟まず、ファイルをテーブルとみなしてSQLを当てます。

CSVファイルの読み込み：read_csvによる自動型推論と区切り指定

基本はSELECT * FROM 'sales.csv'だけで動きます。内部的にはread_csv関数が呼ばれ、区切り文字・ヘッダー有無・各列の型をファイル先頭のサンプルから自動推論する仕組みです。推論が外れる場合だけread_csv('sales.csv', delim=';', header=true)のように明示指定へ切り替える、という順番で書くと手数が減ります。日本の実務データで詰まりやすいのはShift_JISエンコーディングのCSVで、この場合はencodingオプションでの明示指定が必要です。数万行程度なら型推論込みでも読み込みは体感即時で、Excelで開けないサイズのCSVを扱う最初の受け皿として機能します。

Parquetファイルの直接クエリとglobパターンによる複数ファイル一括読み込み

Parquetも同様にSELECT * FROM 'sales.parquet'で直接参照できます。列指向フォーマットであるParquetは必要な列だけを読む設計のため、列を絞ったクエリではCSVより読み取り量が大幅に減る構造です。実務で効くのはglobパターンで、SELECT * FROM '*.parquet'と書けば日次で分割されたファイル群を1つのテーブルとして一括集計できます。データレイクに溜めたParquetをローカルへ持ち出して検証する、という使い方はデータ基盤の設計検証でも定番です。拡張機能のhttpfsをINSTALL httpfsで導入すれば、S3上のParquetへ直接クエリを投げる構成にも広げられます。

JSON読み込みとCOPY文による書き出し：形式変換の実装手順

JSONはread_json_auto('events.json')で読み込み、ネストした構造も構造体型として取り込まれます。改行区切りのJSON Lines形式にも対応しており、アプリケーションログの集計にそのまま使えます。書き出しの担当はCOPY文です。COPY (SELECT ...) TO 'out.parquet' (FORMAT parquet)のように任意のクエリ結果をParquetやCSVへ出力できます。この読み込みと書き出しを組み合わせると、「受領したCSVを検証してParquetへ変換する」形式変換バッチがSQLだけで完結します。変換スクリプトをPythonで書き下ろすより行数が1桁減るのが実際のところです。

PythonからのDuckDB操作：duckdb.sqlとconnect・pandas連携

Pythonライブラリとしての使い方は2つのAPIを押さえれば足ります。束ねて覚えるより、役割の違いで使い分けるのが早道です。

duckdb.sqlとduckdb.connectの使い分けと戻り値の扱い

duckdb.sql('SELECT 1')はモジュール内共有のインメモリDBで即座に実行する書き方で、探索的な分析やノートブックに向きます。一方duckdb.connect('analytics.duckdb')は永続化ファイルへの接続オブジェクトを返し、定期実行するバッチではこちらを使います。戻り値はどちらもRelationオブジェクトです。.df()でpandas DataFrame、.pl()でPolars DataFrame、.fetchall()でPythonのリストに変換できます。遅延評価のため、Relationを組み立てた段階では実行されず、変換メソッドを呼んだ時点で計算が走る点だけ意識しておくとデバッグで迷いません。

pandas・Polars DataFrameを直接クエリする連携の実装

DuckDBのPython連携で特徴的なのは、変数として存在するDataFrameをSQLから直接参照できることです。df = pd.read_csv('sales.csv')としたあと、duckdb.sql('SELECT * FROM df')と書くだけで、登録処理なしにdfがテーブルとして扱われます。pandasで書くと煩雑になる複数キーの結合やウィンドウ関数をSQLに逃がし、結果だけDataFrameに戻す分業が成立する構図です。逆方向も同様で、集計済みRelationを.df()で受ければ、matplotlibでの可視化や機械学習ライブラリへの受け渡しに接続できます。既存のpandas資産を書き換えずに、遅い集計部分だけDuckDBへ差し替える漸進的な移行が現実的な導入形です。

DuckDB採用の判断基準：向くデータ規模と見送るべきシステム条件

ここまでの手順を踏まえ、受託開発でデータ基盤を設計してきた立場から採用条件を言い切ります。迷ったらこの2つの基準で判断してください。

DuckDBを採用する条件：ローカル完結の分析と数十GB規模までのデータ

採用してよいのは、データが単一マシンで処理できる規模（目安として数十GBまで）で、読み手が1人〜少人数に限られる場合です。この条件下では、クラウドDWHの契約・権限設計・コスト管理を持ち込む理由がなく、DuckDBの導入所要時間の短さが効きます。具体的には、月次レポートの集計バッチ、データサイエンティストの前処理環境、受領データの検品ツールが該当例です。分析基盤全体の設計手順やBigQueryとの層構成はデータ分析基盤の構築とは？5層アーキテクチャとBigQuery実装手順を技術視点で解説で整理しているため、DuckDBを基盤のどの層に置くかはそちらと突き合わせて判断できます。

DuckDBを見送る場面：同時書き込みの多い業務システムと全社共有基盤

見送るべき場面は2つです。第一に、複数プロセス・複数ユーザーからの同時書き込みが常時発生するアプリケーションのバックエンド。DuckDBは同一ファイルへの書き込み接続を1プロセスに限定する設計のため、この用途ではPostgreSQLなどのサーバー型RDBMSが正解です。第二に、部署横断でデータを共有し、行レベルの権限管理や監査ログが要る全社基盤。ここは過剰でも不足でもなくクラウドDWHの領分で、データレイクとの組み合わせを含む基盤設計ごと検討すべきです。どの構成が自社の規模に合うか判断がつかない場合は、当社のデータ分析基盤構築・MLOps構築支援で要件整理から設計・実装までを請け負っています。ローカル検証で得た知見を、そのまま本番基盤の要件に翻訳するのが受託側の役割です。

よくある質問

DuckDBの使い方について、検索で相談の多い5つの質問に回答します。

DuckDBは無料で商用利用できますか？

できます。DuckDBはMITライセンスで公開されており、商用プロダクトへの組み込み・社内利用とも追加費用や利用申請は不要です。サポート契約が必要な場合は、開発元メンバーが関与するDuckDB Labsが商用サポートを提供しています。ライセンス費用ゼロで始められるため、PoC段階の稟議が通しやすい点も実務上の利点です。

メモリに載らない大きさのデータも処理できますか？

1.5系時点のDuckDBは、メモリ上限を超える中間結果を一時ファイルへ退避しながら処理するout-of-core実行に対応しています。そのため、搭載メモリより大きいファイルの集計も多くの場合は完走します。ただし退避が発生するとディスクI/O分だけ遅くなるため、恒常的にメモリの数倍のデータを扱うなら、マシン増強かクラウドDWHへの移行を検討する段階です。

SQLiteとはどう使い分ければよいですか？

行単位の書き込みが中心のアプリケーション組み込みDBはSQLite、列の集計・結合が中心の分析はDuckDBです。両者はともにインプロセス型ですが、ストレージ形式（行指向か列指向か)と実行エンジンの設計が逆方向に振られています。本文で触れた通り、詳細な比較は既存記事のDuckDBとは？で扱っています。

S3などクラウドストレージ上のファイルを直接読めますか？

読めます。拡張機能のhttpfsをINSTALL httpfsとLOAD httpfsで有効にすると、s3スキームのURLを指定してS3上のParquetやCSVへ直接クエリできます。認証情報の登録はシークレット管理機能で行う方式です。データレイクのファイルをダウンロードせずにその場で検証できるため、基盤移行前の調査工程で使い勝手が良い機能です。

Windowsでインストール後にCLIが起動しない場合の原因は何ですか？

典型的な原因はMicrosoft Visual C++ Redistributableの不足です。公式サイトも実行に必要になる場合があると注記しており、vcruntime系DLLが見つからない旨のエラーが出たら、Microsoftの配布ページから再頒布パッケージを導入して再実行してください。それでも解決しない場合は、ZIP配布版を任意のフォルダに展開し、PATHを通し直す方法で切り分けます。

関連記事

資料請求

RELATED POSTS 関連記事

一覧へ戻る