What are the best practices for installing dbt v1 with pip?
dbt v2 is a next-generation, Rust-based engine that powers dbt development across the platform and local tooling. See dbt v2 for more information.
Best practices
Managing Python local environments can be challenging! You can use these best practices to improve the dbt v1 installation with pip.
| Best practice | Recommendation | Why it matters |
|---|---|---|
| Install dbt v1 with an adapter and keep versions in sync | Install with: python -m pip install dbt-ADAPTER_NAME (For example, python -m pip install dbt-snowflake) Match adapter versions to your dbt v1 version | Provides a complete, compatible, and ready-to-run dbt setup Prevents runtime errors and adapter incompatibilities |
| For tooling without a warehouse connection, install v1 without an adapter | python -m pip install dbt-core | Keeps your setup lean, predictable, and easier to maintain |
| Use virtual environments | Install dbt in an isolated environment (for example, venv, pipenv, poetry) | Avoids dependency conflicts |
| Reactivate your virtual environment for each session | Reactivate your virtual environment at the start of each new session before installing dependencies or running dbt commands | Keeps your dbt setup predictable, isolated, and reproducible |
| Create a project | Use the dbt init command to create and initialize your first project | Creates a standard dbt project and verifies your installation |
Ensure you have the latest versions of pip, wheel, and setuptools | Before installing dbt, upgrade your Python packaging tools:python -m pip install --upgrade pip wheel setuptools | Helps ensure a smoother, more predictable dbt installation |
Note, dbt adapters and dbt v1 are versioned independently to make it easier for us to maintain and independently evolve adapters going forward.
Using virtual environments
We recommend using virtual environments to namespace pip modules. Here's an example setup:
python3 -m venv dbt-env # create the environment
source dbt-env/bin/activate # activate the environment for Mac and Linux
dbt-env\Scripts\activate # activate the environment for Windows
If you install dbt in a virtual environment, you need to reactivate that same virtual environment each time you create a shell window or session.
Tip: You can create an alias for the source command in your $HOME/.bashrc, $HOME/.zshrc, or whichever rc file your shell draws from. For example, you can add a command like alias env_dbt='source <PATH_TO_VIRTUAL_ENV_CONFIG>/bin/activate', replacing <PATH_TO_VIRTUAL_ENV_CONFIG> with the path to your virtual environment configuration.
Using the latest versions
dbt installations are tested using the latest versions of pip and setuptools. Newer versions have improved behavior around dependency resolution, as well as much faster install times by using precompiled "wheels" when available for your operating system.
Before installing dbt, make sure you have the latest versions:
python -m pip install --upgrade pip wheel setuptools
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
