Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 38 ยท Getting Started

Installing DuckDB and Running Your First Query

Install DuckDB with the CLI, Python, Node.js, R or Java, start a session, run your first SQL queries and learn the one-line ways to query data from the shell.

DuckDB comes in many wrappers, but it is the same engine in each: a single self-contained library with no dependencies. You can try it in under a minute with whichever of the following suits you. This lesson shows each install path, then runs a first few queries and explains the three ways of starting a session.

The install commands below are read-only here, because installing software cannot happen inside a web page. The SQL examples marked "Stand-in" run on SQLite in your browser so that you can practice the query itself.

Installing the command-line shell

The CLI is one small executable called duckdb. Pick the line for your system:

Terminal
# macOS or Linux with Homebrew
brew install duckdb

# Windows with winget
winget install DuckDB.cli

# Any Unix shell: the official install script
curl https://install.duckdb.org | sh

You can also download a ZIP from the DuckDB website, unpack it, and run the duckdb file from any folder. Nothing else is needed. Check it works:

Terminal
duckdb --version

Installing the language clients

If you work in a language rather than a shell, install the client library. They all bundle the same engine:

Terminal
# Python 3.9+
pip install duckdb

# Node.js
npm install @duckdb/node-api

# R
# install.packages("duckdb")

# Java: add org.duckdb:duckdb_jdbc to your build file

Python is the most popular route and has a whole chapter later in this course. Other clients exist for Go, Rust, C, C++, Swift, .NET and more, and DuckDB also compiles to WebAssembly, so it can run inside a browser tab.

Starting a session

In a terminal, type duckdb and press Enter. You will see a prompt, something like D . This is the interactive shell: type SQL, end it with a semicolon, and press Enter.

TEXT
$ duckdb
D SELECT 'hello, duck' AS greeting;

The result appears as a small table in the terminal. To leave, type .exit or press Ctrl+D. Lines starting with a dot, like .exit, are shell commands and not SQL. You will study them in A tour of the DuckDB command line.

There are three common ways to start:

You type What happens
duckdb A temporary, in-memory database. It vanishes when you quit.
duckdb sales.duckdb Opens (or creates) a database file. Changes are saved.
duckdb -c "SELECT 42" Runs one command and exits. Great for scripts.

The first two differ in where the data lives. In-memory and persistent databases covers that in depth.

Your first queries

SQL works without any tables. A SELECT can just compute things:

SQL Stand-in: queries without a table

Press Run (or Ctrl + Enter) to see the result here.

All three statements are valid in DuckDB too. Now create a table, insert a few rows and query it. This is standard SQL and works the same in both engines:

SQL Stand-in: a first table

Press Run (or Ctrl + Enter) to see the result here.

In DuckDB the boolean column holds real true and false, so you would write (true) and (false), and the output shows true. SQLite has no boolean type and stores 1 and 0, which is why the stand-in uses numbers. Data types and casting goes deeper.

Three ways to run SQL from the shell

DuckDB is happy in a pipeline. These are all read-only here, since they need the real program:

Terminal
# 1. One command
duckdb -c "SELECT count(*) FROM 'events.parquet'"

# 2. A script file
duckdb sales.duckdb -c ".read report.sql"

# 3. Pipe SQL in
echo "SELECT 1 + 1" | duckdb

Add -csv or -json to change how the result is printed, for example duckdb -csv -c "SELECT * FROM 'a.csv' LIMIT 3". This turns DuckDB into a handy command-line data tool, like awk with SQL.

Your first file query

Create a tiny file named pets.csv with these lines:

TEXT
name,species,age
Rex,dog,5
Misty,cat,3
Bella,dog,8

Then, in the DuckDB shell, run this read-only query:

SQL
SELECT species, avg(age) AS average_age
FROM 'pets.csv'
GROUP BY species;

There is no CREATE TABLE and no COPY. DuckDB detected the header, the comma delimiter and the column types (age is an integer) by sampling the file. This habit of treating files as tables is the heart of day-to-day DuckDB use.

If something goes wrong

  • "command not found: duckdb": the folder holding the executable is not on your PATH. Run it with the full path, or add the folder to PATH.
  • A prompt that changes to a continuation marker: the shell is waiting for the end of your statement. Finish it with ;.
  • "Catalog Error: Table with name x does not exist": you misspelled a name, or you started a fresh in-memory session and the table was never created there.
  • A locked file: another process has the same .duckdb file open for writing. Close it, or open it with -readonly.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do you type to start DuckDB with a temporary in-memory database?

    Running duckdb with no file name gives a transient in-memory database that disappears when you quit.
  2. 2. What does a line starting with a dot, such as .exit, mean in the DuckDB shell?

    Dot commands control the shell itself (quit, change output mode, list tables). They do not need a semicolon.
  3. 3. How can DuckDB run one query from a script and then exit?

    The -c flag runs the given command and exits, which makes DuckDB easy to use in shell scripts.
  4. 4. Why can DuckDB run SELECT ... FROM 'pets.csv' without a CREATE TABLE?

    DuckDB's CSV reader samples the file and infers the format, so the file itself acts like a table.

Summary

  • DuckDB installs as one CLI executable or as a client library for Python, Node.js, R, Java and more.
  • duckdb alone gives an in-memory database; duckdb file.duckdb persists; duckdb -c "..." runs one command.
  • Dot commands (.exit, .tables) belong to the shell; SQL ends with a semicolon.
  • A file name can stand where a table name goes.

Next: In-memory and persistent databases