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:
- Open VS Code.
- Open a new terminal in VS Code (
Ctrl + ~orCmd + ~, or go to Terminal -> New Terminal). - Run the following command:
python --version
# OR on Mac/Linux
python3 --version - Alternative check using VS Code Command Palette:
- Press
Ctrl + Shift + P(Windows) orCmd + Shift + P(Mac). - Search for "Python: Select Interpreter".
- If installed, you will see a list of Python interpreters available on your system.
- Press
[!WARNING] Challenge Faced (Command Not Recognized) During setup, you might run
python --versionand 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:
- Python is not added to your system's
PATHenvironment variable.- 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
- Check the location of the intercepting file:
where.exe python
# Returns: C:\Users\<User>\AppData\Local\Microsoft\WindowsApps\python.exe - 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
Scriptsfolder 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.exeandpython3.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
- 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/
- If installed via Homebrew, check:
Resolution for macOS
Add Python to your shell PATH environment variable in your shell profile configuration (.zshrc):
- Run the following command in terminal to add Python (Homebrew version) to your PATH:
(If you installed via Python.org, replace
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc/opt/homebrew/binwith the framework bin path, e.g.,/Library/Frameworks/Python.framework/Versions/3.12/bin) - Reload your shell configuration:
source ~/.zshrc - 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:
pipcomes pre-packaged by default. - If
pipis 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
- Run the built-in module:
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
gitfor the first time in terminal, or runxcode-select --install). - Alternatively, install via Homebrew:
brew install git
- Install via Xcode Command Line Tools (automatically prompts when you run
- Linux:
- Ubuntu/Debian:
sudo apt update && sudo apt install git - CentOS/RHEL:
sudo yum install git
- Ubuntu/Debian:
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 pythonorbrew 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.
- The client downloads Python or runs a general installer (like
- Scenario B: After an Automatic System Update (Broken Symlinks)
- The client has a working virtual environment
dbt-envcreated 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.
- The client has a working virtual 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.10Python executable not found- Errors during
pip install dbt-snowflakeindicating incompatible library wheels or C compilation errors.
Root Cause
- 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.
- 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:
Method A: Command Line Installation (Recommended & Faster)
- For Windows (using Winget):
- Open your terminal (PowerShell or Command Prompt) in VS Code.
- Run the command:
winget install Python.Python.3.10 - Wait for the installer to finish.
- For macOS (using Homebrew):
- Open your terminal in VS Code.
- Run the command:
brew install python@3.10 - Wait for Homebrew to download and link Python 3.10.
Method B: Graphical Installer (Via Web Browser)
- For Windows:
- Open your web browser and go to the official Python 3.10.11 Downloads Page.
- Scroll to the bottom and click on Windows installer (64-bit) to download the
.exefile. - Run the downloaded installer.
- 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.
- Click Install Now and complete the installation.
- For macOS:
- Open your web browser and go to the official Python 3.10.11 Downloads Page.
- Scroll to the bottom and click on macOS 64-bit universal2 installer to download the
.pkgfile. - Double-click the downloaded
.pkgfile to open the installation wizard. - 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):
- Ensure you are in the directory containing the
dbt-envfolder. - Run:
Remove-Item -Recurse -Force .\dbt-env
- Ensure you are in the directory containing the
- For Windows (Command Prompt):
- Run:
rmdir /s /q dbt-env
- Run:
- For macOS / Linux (Terminal):
- Run:
rm -rf dbt-env
- Run:
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:
- Create the environment specifying the Python 3.10 version:
py -3.10 -m venv dbt-env - Activate the environment:
- If using PowerShell:
.\dbt-env\Scripts\Activate.ps1 - If using Command Prompt:
dbt-env\Scripts\activate.bat
- If using PowerShell:
- Create the environment specifying the Python 3.10 version:
- For macOS / Linux:
- Create the environment specifying the Python 3.10 binary path:
python3.10 -m venv dbt-env - Activate the environment:
source dbt-env/bin/activate
- Create the environment specifying the Python 3.10 binary path:
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!
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.