Skip to content
Get packs

Guide · Open source

How to use DuckDB: install, query files and get started

Updated · written with AI from the project's own documentation and checked against our catalogue data

DuckDB is an open-source analytical database system (MIT licensed, written in C++) that runs inside your application instead of as a separate server. This guide explains what it does, how to query files directly with SQL, how to attach other databases, and where to go next. By the end you will know which entry point fits your work and how to run your first query.

DuckDBduckdb/duckdb · ★ 42.7k · MIT

Quick start

  1. 1Pick your entry point. Choose the CLI for direct SQL, or a client such as Python or R if your data already lives there.
  2. 2Install DuckDB. Follow the official installation page for your operating system.
  3. 3Open a session. Start DuckDB so you have a session in which to run SQL.
  4. 4Query a file. Use SELECT * FROM with the path to a CSV or Parquet file.
  5. 5Attach another database. If needed, attach a PostgreSQL, MySQL, or SQLite database and query it in place.
  6. 6Learn the dialect. Read the SQL reference for subqueries, window functions and complex types.

What DuckDB is and who it is for

DuckDB is built for analytical queries, the kind that summarize and combine large amounts of data. It runs in-process, so there is no separate server to manage and no external dependencies. The project describes itself as designed to be fast, reliable, portable, and easy to use.

  • Analysts who want to run SQL directly on CSV, Parquet, or JSON files
  • Python or R users who work with pandas-style data and want fast SQL
  • Developers embedding an analytical database in an application without running a server
  • Students learning SQL on realistic data sets

Install DuckDB and open it

The project's README points to an installation page with instructions for each platform, and lists no prerequisites for installing. It also offers a standalone CLI application and clients for Python, R, Java, Rust, Go, Wasm and more. Choose the client that matches your work, then follow the official installation page for your system.

If you want to work with the source code itself, the README shows how to clone the repository.

  • Standalone CLI: the easiest way to type SQL and see results
  • Python or R: use the client if your data already lives in those tools
  • Clone the source with the command below if you plan to build or contribute
git clone https://github.com/duckdb/duckdb

Query CSV, Parquet and JSON files with SQL

For many formats, including CSV, Parquet, and JSON, you load data by referencing the file in the FROM clause. You do not need to create a table first. The README shows this pattern for CSV and Parquet files.

  • Replace myfile.csv with the path to your own file
  • Use the same pattern with .parquet files
  • DuckDB can also read remote files from S3, HTTP(S), Azure, and Google Cloud Storage
SELECT * FROM 'myfile.csv'; SELECT * FROM 'myfile.parquet';

Attach PostgreSQL, MySQL or SQLite databases

DuckDB can attach to other database systems and query them in place, so you can read, join, and move data across engines without a separate ETL step. It speaks the native protocols of PostgreSQL, MySQL, and SQLite. Check the linked extension documentation for the exact syntax for each database.

Use the SQL features and extensions

DuckDB supports a rich SQL dialect: arbitrary and nested correlated subqueries, window functions, collations, and complex types such as arrays, structs, and maps. Its friendly SQL extensions add syntax that makes queries shorter and easier to write. The SQL introduction and reference in the documentation covers the full dialect.

Extensions add file formats, database connectors, and new functions and types. Core extensions are bundled, and community or third-party extensions can be installed and loaded at runtime.

  • Read the SQL introduction and reference in the official documentation
  • Browse the extension mechanism docs before building custom workarounds

Build from source (for developers)

For development, the README says DuckDB requires CMake, Python 3 and a C++17 compliant compiler. Run make in the root directory to compile the sources. Use make debug for a non-optimized debug build, and run make unit and make allunit to verify your changes. Read the Build Guide and Contribution Guide before submitting changes.

  • Requirements: CMake, Python 3, C++17 compiler
  • make compiles the sources; make debug builds a debug version
  • Run make unit and make allunit after changes
make make debug make unit make allunit

What people use it for

  • Run SQL on a folder of CSV exports without loading them into a server
  • Query Parquet files stored locally or in cloud storage
  • Join data from a SQLite file with a PostgreSQL database in one query
  • Embed an analytical database in an application that must not run a server

Frequently asked questions

Is DuckDB free to use?

DuckDB is released under the MIT licence, which the project lists in its repository details. Check the licence file in the repository for the full terms.

Does DuckDB need a server?

No. DuckDB runs in-process inside your application, so there is no separate server to manage. Its README describes it as having no external dependencies.

Can DuckDB query CSV and Parquet files directly?

Yes. For CSV, Parquet, and JSON you can reference the file in the FROM clause, for example SELECT * FROM 'myfile.csv';. No table creation step is shown in the README.

What are the alternatives to DuckDB?

Comparable projects named for this item include SQLite, PostgreSQL, ClickHouse, and Polars. SQLite and PostgreSQL are general-purpose databases, while ClickHouse and Polars are also aimed at analytical work.

Is DuckDB good for many concurrent writers?

Not for that use case. DuckDB is designed for analytics rather than high-volume transactional (OLTP) workloads with many concurrent writers, so a transactional database is a better fit there.

Is there a hosted DuckDB service?

The README describes an embedded system and support options rather than a fully managed hosted product. If you need hosting, look for another solution.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

DuckDB suits analysts, Python and R users, developers embedding analytics, and students who want SQL on files and data they already have. Pick something else if you need a high-volume transactional database for many concurrent writers or a fully managed hosted service.

Install options & downloads