Implementation:Astronomer Astronomer cosmos ProjectConfig Init

Metadata

Field	Value
Page Type	Implementation
Repository	astronomer-cosmos
Source File	`cosmos/config.py`, Lines L159-277
Implements	Principle:Astronomer_Astronomer_cosmos_Project_Path_Configuration
Import	`from cosmos.config import ProjectConfig`

Overview

ProjectConfig is the concrete tool provided by the astronomer-cosmos library for configuring dbt project paths and metadata within an Airflow orchestration context. It encapsulates all filesystem-related configuration needed to locate and describe a dbt project, including the project root, relative subdirectory paths, manifest location, environment variables, and dbt variables.

This class serves as the primary entry point for telling cosmos where a dbt project lives and what its structure looks like.

Source Location

Property	Value
Repository	astronomer-cosmos
File	`cosmos/config.py`
Lines	L159-277
Class	`ProjectConfig`

Code Reference

Signature

class ProjectConfig:
    def __init__(
        self,
        dbt_project_path: str | Path | None = None,
        install_dbt_deps: bool = True,
        copy_dbt_packages: bool = settings.default_copy_dbt_packages,
        models_relative_path: str | Path = "models",
        seeds_relative_path: str | Path = "seeds",
        snapshots_relative_path: str | Path = "snapshots",
        manifest_path: str | Path | None = None,
        manifest_conn_id: str | None = None,
        project_name: str | None = None,
        env_vars: dict[str, str] | None = None,
        dbt_vars: dict[str, str] | None = None,
        partial_parse: bool = True,
    ):

Import Statement

from cosmos.config import ProjectConfig

Parameters

Parameter	Type	Default	Description
`dbt_project_path`	Path \| None	`None`	Absolute or relative path to the directory containing `dbt_project.yml`.
`install_dbt_deps`	`bool`	`True`	Whether to run `dbt deps` before execution to install package dependencies.
`copy_dbt_packages`	`bool`	`settings.default_copy_dbt_packages`	Whether to copy dbt packages into the project directory for isolated execution.
`models_relative_path`	Path	`"models"`	Relative path from the project root to the models directory.
`seeds_relative_path`	Path	`"seeds"`	Relative path from the project root to the seeds directory.
`snapshots_relative_path`	Path	`"snapshots"`	Relative path from the project root to the snapshots directory.
`manifest_path`	Path \| None	`None`	Path to a pre-compiled `manifest.json` file. Enables manifest-based parsing.
`manifest_conn_id`	None	`None`	Airflow connection ID for retrieving a remote manifest file.
`project_name`	None	`None`	Explicit project name override. Inferred from `dbt_project.yml` if not provided.
`env_vars`	None	`None`	Environment variables to inject into the dbt execution environment.
`dbt_vars`	None	`None`	dbt variables passed via `--vars` flag to dbt commands.
`partial_parse`	`bool`	`True`	Whether to enable dbt partial parsing for faster re-parsing of unchanged models.

I/O Contract

Inputs

The constructor accepts filesystem paths and optional settings:

Required (one of): Either dbt_project_path or manifest_path must be provided. If neither is given, the configuration is invalid.
Optional: All other parameters have sensible defaults following dbt conventions.

Outputs

A ProjectConfig instance with the following resolved attributes:

dbt_project_path — Resolved Path object pointing to the project root directory.
models_relative_path — Resolved Path for the models subdirectory.
seeds_relative_path — Resolved Path for the seeds subdirectory.
snapshots_relative_path — Resolved Path for the snapshots subdirectory.
project_name — The project name, either explicitly provided or inferred from dbt_project.yml.
manifest_path — Resolved Path to the manifest file, if provided.

Validation

During initialization, the following validations are performed:

If dbt_project_path is provided, it is checked for the existence of dbt_project.yml.
If project_name is not explicitly set and dbt_project_path is provided, the name is parsed from dbt_project.yml.
Path objects are resolved to absolute paths for consistency.

Usage Examples

Basic Usage with Project Path

from cosmos.config import ProjectConfig

# Configure with a local dbt project path
project_config = ProjectConfig(
    dbt_project_path="/usr/local/airflow/dags/dbt/my_project",
)

In this example, cosmos will look for dbt_project.yml at the specified path and use default relative paths for models, seeds, and snapshots.

Usage with Manifest Path

from cosmos.config import ProjectConfig

# Configure with a pre-compiled manifest (no local dbt project needed)
project_config = ProjectConfig(
    manifest_path="/usr/local/airflow/dags/dbt/target/manifest.json",
    project_name="my_project",
)

When using a manifest path, the project name must be explicitly provided since there is no dbt_project.yml to infer it from.

Usage with Custom Paths and Variables

from cosmos.config import ProjectConfig

# Configure with custom subdirectory paths, env vars, and dbt vars
project_config = ProjectConfig(
    dbt_project_path="/usr/local/airflow/dags/dbt/my_project",
    models_relative_path="transformations",
    seeds_relative_path="data",
    snapshots_relative_path="scd",
    env_vars={
        "DBT_PROFILES_DIR": "/usr/local/airflow/dags/dbt",
        "WAREHOUSE": "analytics_wh",
    },
    dbt_vars={
        "start_date": "2024-01-01",
        "schema_prefix": "prod",
    },
    partial_parse=True,
)

Usage within a DbtTaskGroup

from cosmos import DbtTaskGroup, ProjectConfig, ProfileConfig, RenderConfig

project_config = ProjectConfig(
    dbt_project_path="/usr/local/airflow/dags/dbt/my_project",
    install_dbt_deps=True,
)

dbt_tasks = DbtTaskGroup(
    project_config=project_config,
    profile_config=profile_config,
    render_config=RenderConfig(),
)

Related Pages

Implements Principle

Principle:Astronomer_Astronomer_cosmos_Project_Path_Configuration — The principle this implementation realizes.

Complementary Implementations

Implementation:Astronomer_Astronomer_cosmos_ProfileConfig_Init — Complementary implementation for database profile configuration.
Implementation:Astronomer_Astronomer_cosmos_RenderConfig_Init — Complementary implementation for graph rendering configuration.
Implementation:Astronomer_Astronomer_cosmos_ExecutionConfig_Init — Complementary implementation for runtime execution configuration.

Requires Environment

Uses Heuristic

Heuristic:Astronomer_Astronomer_cosmos_Memory_Optimised_Imports

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment