---
title: "Quickstart for dbt Core from a manual install"
source: dbt Core Documentation
source_url: https://github.com/dbt-labs/docs.getdbt.com
licence: Apache-2.0
domain: data-and-analysis
subdomain: dbt-docs
date_added: 2026-04-25
---

## Introduction

When you use <Constant name="core" /> to work with dbt, you will be editing files locally using a code editor, and running projects using a command line interface (CLI). 

If you want to edit files and run projects using the web-based dbt Integrated Development Environment (<Constant name="studio_ide" />), refer to the [<Constant name="dbt" /> quickstarts](/guides). You can also develop and run dbt commands using the [<Constant name="dbt" /> CLI](/docs/cloud/cloud-cli-installation) &mdash; a <Constant name="dbt" /> powered command line.

### Prerequisites

* To use dbt Core, it's important that you know some basics of the Terminal. In particular, you should understand `cd`, `ls` and `pwd` to navigate through the directory structure of your computer easily.
* Install <Constant name="core" /> using the [installation instructions](/docs/local/install-dbt) for your operating system.
* Complete appropriate Setting up and Loading data steps in the Quickstart for <Constant name="dbt" /> series. For example, for BigQuery, complete [Setting up (in BigQuery)](/guides/bigquery?step=2) and [Loading data (BigQuery)](/guides/bigquery?step=3).
* [Create a GitHub account](https://github.com/join) if you don't already have one.

### Create a starter project

After setting up BigQuery to work with dbt, you are ready to create a starter project with example models, before building your own models.

## Create a repository

The following steps use [GitHub](https://github.com/) as the <Constant name="git" /> provider for this guide, but you can use any <Constant name="git" /> provider. You should have already [created a GitHub account](https://github.com/join).

1. [Create a new GitHub repository](https://github.com/new) named `dbt-tutorial`.
2. Select one of the following (You can always change this setting later):
    - **Private (recommended):** To secure your environment and prevent private information (like credentials) from being public.
    - **Public:** If you need to easily collaborate and share with others, especially outside of your organization. 

3. Leave the default values for all other settings.
4. Click **Create repository**.
5. Save the commands from "…or create a new repository on the command line" to use later in [Commit your changes](/guides/manual-install?step=6).

## Create a project

Learn how to use a series of commands using the command line of the Terminal to create your project. dbt Core includes an `init` command that helps scaffold a dbt project.

To create your dbt project:

1. Make sure you have dbt Core installed and check the version using the `dbt --version` command:

```shell
dbt --version
```

2. Initiate the `jaffle_shop` project using the `init` command:

```shell
dbt init jaffle_shop
```

3. Navigate into your project's directory:

```shell
cd jaffle_shop
```

4. Use `pwd` to confirm that you are in the right spot:

```shell
$ pwd
> Users/BBaggins/dbt-tutorial/jaffle_shop
```

5. Use a code editor like Atom or VSCode to open the project directory you created in the previous steps, which we named jaffle_shop. The content includes folders and `.sql` and `.yml` files generated by the `init` command.


<Lightbox src="/img/starter-project-dbt-cli.png" title="The starter project in a code editor" />


6. dbt provides the following values in the `dbt_project.yml` file:

<File name='dbt_project.yml'>

```yaml
name: jaffle_shop # Change from the default, `my_new_project`

...

profile: jaffle_shop # Change from the default profile name, `default`

...

models:
    jaffle_shop: # Change from `my_new_project` to match the previous value for `name:`
    ...
```

</File>

## Connect to BigQuery

When developing locally, dbt connects to your <Term id="data-warehouse" /> using a [profile](/docs/local/profiles.yml), which is a YAML file with all the connection details to your warehouse. 

1. Create a file in the `~/.dbt/` directory named `profiles.yml`.
2. Move your BigQuery keyfile into this directory.
3. Copy the following and paste into the new profiles.yml file. Make sure you update the values where noted.

<File name='profiles.yml'>

```yaml
jaffle_shop: # this needs to match the profile in your dbt_project.yml file
    target: dev
    outputs:
        dev:
            type: bigquery
            method: service-account
            keyfile: /Users/BBaggins/.dbt/dbt-tutorial-project-331118.json # replace this with the full path to your keyfile
            project: grand-highway-265418 # Replace this with your project id
            dataset: dbt_bbagins # Replace this with dbt_your_name, e.g. dbt_bilbo
            threads: 1
            timeout_seconds: 300
            location: US
            priority: interactive
```

</File>

4. Run the `debug` command from your project to confirm that you can successfully connect:

```shell
$ dbt debug
> Connection test: OK connection ok
```


<Lightbox src="/img/successful-dbt-debug.png" title="A successful dbt debug command" />


### FAQs

<FAQ path="Warehouse/sample-profiles" alt_header="My data team uses a different data warehouse. What should my profiles.yml file look like for my warehouse?"/>
<FAQ path="Project/separate-profile" />
<FAQ path="Environments/profile-name" />
<FAQ path="Environments/target-names" />
<FAQ path="Environments/profile-env-vars" />

## Perform your first dbt run

Our sample project has some example models in it. We're going to check that we can run them to confirm everything is in order.

1. Enter the `run` command to build example models:

```shell
dbt run
```

You should have an output that looks like this:


<Lightbox src="/img/successful-dbt-run.png" title="A successful dbt run command" />


## Commit your changes

Commit your changes so that the repository contains the latest code.

1. Link the GitHub repository you created to your dbt project by running the following commands in Terminal. Make sure you use the correct git URL for your repository, which you should have saved from step 5 in [Create a repository](/guides/manual-install?step=2).

```shell
git init
git branch -M main
git add .
git commit -m "Create a dbt project"
git remote add origin https://github.com/USERNAME/dbt-tutorial.git
git push -u origin main
```

2. Return to your GitHub repository to verify your new files have been added.

### Build your first models

Now that you set up your sample project, you can get to the fun part — [building models](/docs/build/sql-models)! 
In the next steps, you will take a sample query and turn it into a model in your dbt project.

## Checkout a new git branch

Check out a new git branch to work on new code:

1. Create a new branch by using the `checkout` command and passing the `-b` flag:

```shell
$ git checkout -b add-customers-model
>  Switched to a new branch `add-customer-model`
```

## Build your first model


1. Open your project in your favorite code editor.
2. Create a new SQL file in the `models` directory, named `models/customers.sql`.
3. Paste the following query into the `models/customers.sql` file.

<Snippet path="tutorial-sql-query" />

4. From the command line, enter `dbt run`.

<Lightbox src="/img/first-model-dbt-cli.png" title="A successful run with the dbt Core CLI" />


When you return to the BigQuery console, you can `select` from this model.

### FAQs

<FAQ path="Runs/checking-logs" />
<FAQ path="Project/which-schema" />
<FAQ path="Models/create-a-schema" />
<FAQ path="Models/run-downtime" />
<FAQ path="Troubleshooting/sql-errors" />

## Change the way your model is materialized


<Snippet path="quickstarts/change-way-model-materialized" />

## Delete the example models

<Snippet path="quickstarts/delete-example-models" />

## Build models on top of other models

<Snippet path="quickstarts/intro-build-models-atop-other-models" />

1. Create a new SQL file, `models/stg_customers.sql`, with the SQL from the `customers` CTE in our original query.
2. Create a second new SQL file, `models/stg_orders.sql`, with the SQL from the `orders` CTE in our original query.

<WHCode>


<File name='models/stg_customers.sql'>

```sql
select
    id as customer_id,
    first_name,
    last_name

from `dbt-tutorial`.jaffle_shop.customers
```

</File>

<File name='models/stg_orders.sql'>

```sql
select
    id as order_id,
    user_id as customer_id,
    order_date,
    status

from `dbt-tutorial`.jaffle_shop.orders
```

</File>


<File name='models/stg_customers.sql'>

```sql
select
    id as customer_id,
    first_name,
    last_name

from jaffle_shop_customers
```

</File>

<File name='models/stg_orders.sql'>

```sql
select
    id as order_id,
    user_id as customer_id,
    order_date,
    status

from jaffle_shop_orders
```

</File>


<File name='models/stg_customers.sql'>

```sql
select
    id as customer_id,
    first_name,
    last_name

from jaffle_shop.customers
```

</File>

<File name='models/stg_orders.sql'>

```sql
select
    id as order_id,
    user_id as customer_id,
    order_date,
    status

from jaffle_shop.orders
```

</File>


<File name='models/stg_customers.sql'>

```sql
select
    id as customer_id,
    first_name,
    last_name

from raw.jaffle_shop.customers
```

</File>

<File name='models/stg_orders.sql'>

```sql
select
    id as order_id,
    user_id as customer_id,
    order_date,
    status

from raw.jaffle_shop.orders
```

</File>


</WHCode>

3. Edit the SQL in your `models/customers.sql` file as follows:

<File name='models/customers.sql'>

```sql
with customers as (

    select * from {{ ref('stg_customers') }}

),

orders as (

    select * from {{ ref('stg_orders') }}

),

customer_orders as (

    select
        customer_id,

        min(order_date) as first_order_date,
        max(order_date) as most_recent_order_date,
        count(order_id) as number_of_orders

    from orders

    group by 1

),

final as (

    select
        customers.customer_id,
        customers.first_name,
        customers.last_name,
        customer_orders.first_order_date,
        customer_orders.most_recent_order_date,
        coalesce(customer_orders.number_of_orders, 0) as number_of_orders

    from customers

    left join customer_orders using (customer_id)

)

select * from final

```

</File>

4. Execute `dbt run`.

This time, when you performed a `dbt run`, separate views/tables were created for `stg_customers`, `stg_orders` and `customers`. dbt inferred the order to run these models. Because `customers` depends on `stg_customers` and `stg_orders`, dbt builds `customers` last. You do not need to explicitly define these dependencies.

### FAQs {#faq-2}

<FAQ path="Runs/run-one-model" />
<FAQ path="Project/unique-resource-names" />
<FAQ path="Project/structure-a-project" alt_header="As I create more models, how should I keep my project organized? What should I name my models?" />

### Next steps

<Snippet path="tutorial-next-steps-1st-model" />

You can also explore:

* The `target` directory to see all of the compiled SQL. The `run` directory shows the create or replace table statements that are running, which are the select statements wrapped in the correct DDL.
* The `logs` file to see how dbt Core logs all of the action happening within your project. It shows the select statements that are running and the python logging happening when dbt runs.

## Add tests to your models

<Snippet path="tutorial-add-tests-to-models" />

## Document your models

<Snippet path="tutorial-document-your-models" />

3. Run `dbt docs serve` command to launch the documentation in a local website.

#### FAQs

<FAQ path="Docs/long-descriptions" />
<FAQ path="Docs/sharing-documentation" />


#### Next steps

<Snippet path="tutorial-next-steps-tests" />

## Commit updated changes

You need to commit the changes you made to the project so that the repository has your latest code.

1. Add all your changes to git: `git add -A`
2. Commit your changes: `git commit -m "Add customers model, tests, docs"`
3. Push your changes to your repository: `git push -u origin add-customers-model`
4. Navigate to your repository, and open a pull request to merge the code into your master branch.

## Schedule a job

We recommend using <Constant name="dbt" /> as the easiest and most reliable way to [deploy jobs](/docs/deploy/deployments) and automate your dbt project in production. 

For more info on how to get started, refer to [create and schedule jobs](/docs/deploy/deploy-jobs#create-and-schedule-jobs).

<Lightbox src="/img/docs/dbt-cloud/deployment/run-overview.png" width="90%" title="Overview of a dbt job run, which includes the job run details, trigger type, commit SHA, environment name, detailed run steps, logs, and more."/>

For more information about using <Constant name="core" /> to schedule a job, refer [dbt airflow](/blog/dbt-airflow-spiritual-alignment) blog post.
