Skip to main content

01. Installing DBT Core

Installing DBT Core​

DBT Core is an open-source command-line tool that allows you to run your data transformation projects locally or on a server. Since it is purely a CLI tool, it runs in any environment that supports Python.


1. Prerequisites & System Setup​

Before installing DBT Core, you must set up the core system dependencies on your machine.


A. Python (3.8 - 3.12)​

DBT Core is a Python-based utility. It requires Python version 3.8 to 3.12 (Python 3.13+ or 3.14+ are currently not fully supported by all DBT adapters).

How to Check if Python is Installed in VS Code:​
  1. Open VS Code.
  2. Open a new terminal in VS Code (Ctrl + ~ or Cmd + ~, or go to Terminal -> New Terminal).
  3. Run the following command:
    python --version
    # OR on Mac/Linux
    python3 --version
  4. Alternative check using VS Code Command Palette:
    • Press Ctrl + Shift + P (Windows) or Cmd + Shift + P (Mac).
    • Search for "Python: Select Interpreter".
    • If installed, you will see a list of Python interpreters available on your system.

[!WARNING] Challenge Faced (Command Not Recognized) During setup, you might run python --version and see:

  • "Python was not found; run without arguments to install from the Microsoft Store..." OR
  • 'python' is not recognized as an internal or external command.

This happens because:

  1. Python is not added to your system's PATH environment variable.
  2. Windows App Execution Aliases are redirecting to the Microsoft Store.

For the step-by-step resolution of this challenge, see the troubleshooting dropdown below.

🛠️ Troubleshooting Python Command Recognition Issues (PATH & OS-Specific Aliases)

During the installation of Python, you may encounter issues where the command python or python3 is not recognized by your terminal (VS Code). Find your operating system below for step-by-step resolution:


For Windows Users​

Symptoms​

Python installation completed successfully (e.g., using winget or the official installer), but:

python --version

returns:

Python was not found; run without arguments to install from the Microsoft Store...

Investigation & Commands​

  1. Check the location of the intercepting file:
    where.exe python
    # Returns: C:\Users\<User>\AppData\Local\Microsoft\WindowsApps\python.exe
  2. Verify actual installation location (usually under Program Files or AppData Programs):
    dir "$env:LOCALAPPDATA\Programs\Python"
    # Usually lists: Python312

Resolution for Windows​

  • Permanently Add Python to PATH: Add the installation directory and its Scripts folder to your User/System environment variables. Or via command line:
    setx PATH "%PATH%;C:\Users\<User>\AppData\Local\Programs\Python\Python312;C:\Users\<User>\AppData\Local\Programs\Python\Python312\Scripts"
  • Disable Microsoft Store App Execution Aliases: Go to Settings -> Apps -> Advanced App Settings -> App Execution Aliases. Turn OFF python.exe and python3.exe.
  • Restart VS Code Terminal to apply changes.

For macOS Users​

Symptoms​

Python was installed (via homebrew or python.org), but running:

python3 --version

returns:

zsh: command not found: python3

Investigation & Commands​

  1. Check where Python is installed:
    • If installed via Homebrew, check:
      ls -l /opt/homebrew/bin/python3
      # OR for older Intel-based Macs:
      ls -l /usr/local/bin/python3
    • If installed via the official Python.org package, check:
      ls -l /Library/Frameworks/Python.framework/Versions/

Resolution for macOS​

Add Python to your shell PATH environment variable in your shell profile configuration (.zshrc):

  1. Run the following command in terminal to add Python (Homebrew version) to your PATH:
    echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
    (If you installed via Python.org, replace /opt/homebrew/bin with the framework bin path, e.g., /Library/Frameworks/Python.framework/Versions/3.12/bin)
  2. Reload your shell configuration:
    source ~/.zshrc
  3. Verify it is now recognized:
    python3 --version

B. pip (Python Package Installer)​

pip is Python's package manager, which you will use to install DBT and its adapters.

How to Check if pip is Installed:​

In your VS Code terminal, run:

pip --version
# OR on Mac/Linux
pip3 --version
How to Install pip:​
  • If Python was installed via Python.org or official installers: pip comes pre-packaged by default.
  • If pip is missing, you can bootstrap it:
    • Run the built-in module:
      python -m ensurepip --default-pip
    • Alternatively, download and run the bootstrap script:
      curl https://bootstrap.pypy.io/get-pip.py -o get-pip.py
      python get-pip.py

C. Git (Version Control System)​

Git is required to manage your DBT code, track changes, and clone/push projects.

How to Check if Git is Installed:​

In your VS Code terminal, run:

git --version
How to Install Git:​
  • Windows:
    • Download and run the official installer from git-scm.com.
    • Alternatively, run via winget:
      winget install Git.Git
  • Mac:
    • Install via Xcode Command Line Tools (automatically prompts when you run git for the first time in terminal, or run xcode-select --install).
    • Alternatively, install via Homebrew:
      brew install git
  • Linux:
    • Ubuntu/Debian: sudo apt update && sudo apt install git
    • CentOS/RHEL: sudo yum install git

Best Practice: Use Virtual Environments

It is highly recommended to install DBT inside a Python virtual environment to avoid dependency conflicts with other Python projects on your machine.


2. Step-by-Step Installation Guide​

Step A: Create and Activate a Virtual Environment​

Depending on your operating system, open your terminal in VS Code and run the following:

Mac/Linux:

python3 -m venv dbt-env
source dbt-env/bin/activate

Windows:

python -m venv dbt-env
dbt-env\Scripts\activate

🔍 Troubleshooting: Unsupported Python Version / Broken Virtual Environment

If you run into issues during virtual environment creation or when running DBT inside the environment, it is likely due to using an unsupported Python version (e.g., Python 3.13, 3.14+) or having a corrupted environment setup.

When Does This Issue Occur?​

This issue typically arises in one of two scenarios:

  • Scenario A: A Brand New Setup (Bleeding-Edge Default Python)
    • The client downloads Python or runs a general installer (like winget install python or brew install python) which installs the absolute latest version (e.g., Python 3.13 or 3.14).
    • They create a virtual environment (python -m venv dbt-env) which inherits this latest Python.
    • When attempting to install DBT inside it (pip install dbt-snowflake), the installation fails because DBT and database adapters (like Snowflake's connector) do not yet support this new Python version.
  • Scenario B: After an Automatic System Update (Broken Symlinks)
    • The client has a working virtual environment dbt-env created previously.
    • Later, their main system Python is updated, upgraded, or uninstalled (replacing the active binary with Python 3.14).
    • The virtual environment's internal links (symlinks) to Python become broken, resulting in errors when trying to run DBT or activate the environment.

Symptoms & Errors​

When trying to run or install DBT, you might see one of these errors in your VS Code terminal:

  • No runtime installed that matches 3.10
  • Python executable not found
  • Errors during pip install dbt-snowflake indicating incompatible library wheels or C compilation errors.

Root Cause​

  1. The virtual environment was created using a version of Python (such as Python 3.14) that the current release of DBT does not yet support.
  2. The environment's internal references point to an incorrect or deleted Python directory.

Step-by-Step Resolution (Complete & Detailed)​

Step 1: Install a Supported Python Version (Python 3.10 or 3.12)​

Make sure you have a supported Python version installed on your machine. You can install it using either the Command Line (recommended) or the Graphical Installer:

  • For Windows (using Winget):
    1. Open your terminal (PowerShell or Command Prompt) in VS Code.
    2. Run the command:
      winget install Python.Python.3.10
    3. Wait for the installer to finish.
  • For macOS (using Homebrew):
    1. Open your terminal in VS Code.
    2. Run the command:
      brew install python@3.10
    3. Wait for Homebrew to download and link Python 3.10.
Method B: Graphical Installer (Via Web Browser)​
  • For Windows:
    1. Open your web browser and go to the official Python 3.10.11 Downloads Page.
    2. Scroll to the bottom and click on Windows installer (64-bit) to download the .exe file.
    3. Run the downloaded installer.
    4. CRITICAL STEP: Before clicking "Install Now", make sure to check the box that says "Add Python 3.10 to PATH" at the bottom of the installer window.
    5. Click Install Now and complete the installation.
  • For macOS:
    1. Open your web browser and go to the official Python 3.10.11 Downloads Page.
    2. Scroll to the bottom and click on macOS 64-bit universal2 installer to download the .pkg file.
    3. Double-click the downloaded .pkg file to open the installation wizard.
    4. Click Continue, agree to the terms, and complete the installation.
Step 2: Delete the Existing/Corrupted Virtual Environment Folder​

Before creating a new environment, you must completely remove the old, broken one.

  • For Windows (PowerShell):
    1. Ensure you are in the directory containing the dbt-env folder.
    2. Run:
      Remove-Item -Recurse -Force .\dbt-env
  • For Windows (Command Prompt):
    1. Run:
      rmdir /s /q dbt-env
  • For macOS / Linux (Terminal):
    1. Run:
      rm -rf dbt-env
Step 3: Recreate the Virtual Environment targeting Python 3.10​

Now, create a fresh virtual environment specifically linked to the supported Python 3.10 version.

  • For Windows:
    1. Create the environment specifying the Python 3.10 version:
      py -3.10 -m venv dbt-env
    2. Activate the environment:
      • If using PowerShell:
        .\dbt-env\Scripts\Activate.ps1
      • If using Command Prompt:
        dbt-env\Scripts\activate.bat
  • For macOS / Linux:
    1. Create the environment specifying the Python 3.10 binary path:
      python3.10 -m venv dbt-env
    2. Activate the environment:
      source dbt-env/bin/activate
Step 4: Verify the Active Python Version​

Inside your active environment (you should see (dbt-env) prefixed in your terminal prompt), run:

python --version

It must output Python 3.10.x. You are now ready to safely install DBT without compatibility issues!


Step B: Install the DBT Adapter​

Unlike other tools, you rarely install dbt-core directly. Instead, you install the adapter specific to your Data Warehouse. Installing the adapter automatically installs dbt-core as a dependency.

# For Snowflake users
pip install dbt-snowflake

# For BigQuery users
pip install dbt-bigquery

# For Postgres users
pip install dbt-postgres

3. Verifying the Installation​

Once installed, verify that the CLI is accessible and check the version:

dbt --version

If successful, the terminal will return the installed version of dbt-core along with the version of your installed warehouse adapter:

Core:
- installed: 1.10.7
- latest: 1.11.8 - Update available!

Plugins:
- snowflake: 1.10.0 - Update available!
Upgrading DBT

To upgrade DBT in the future, simply run: pip install --upgrade dbt-snowflake (or your respective adapter).


Next Steps​

Now that your machine is fully equipped with DBT Core and your cloud-specific adapter, it is time to move on to the next module: Creating your very first DBT Project.