Install & Compatibility
Where this runs
tested against v0.25.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 32.36s
py 3.11
✕ build_error
✓ 28.51s
py 3.12
✕ build_error
✓ 28.4s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 36.76s
503MB installed
● package 503MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CLI Tool (pb)
✓ Interaction is primarily via the 'pb' command-line interface.
profiles-rudderstack is designed as a CLI tool for managing data warehouse profiles. Direct programmatic imports for end-user functionality from the Python package are not the primary use case; instead, it generates and executes SQL based on YAML configurations managed by the 'pb' CLI. The 'Profiles API' is an external HTTP API to trigger runs, not a Python library import.
This quickstart guides you through installing the `profiles-rudderstack` CLI tool (aliased as `pb`), setting up a warehouse connection, initializing a Profiles project, configuring it with YAML files, validating access, and finally running the project to generate customer profiles in your data warehouse.
# 1. Install Profiles Builder
pip install profiles-rudderstack
# 2. Verify installation
pb version
# 3. Create warehouse connection (follow prompts)
pb init connection
# 4. Initialize a new Profiles project in a directory 'my-project'
pb init pb-project -o my-project
cd my-project
# 5. Open pb_project.yaml and set 'connection:' to your connection name.
# Edit inputs.yaml and profiles.yaml with your data sources and features.
# 6. Validate warehouse access
pb validate access
# 7. Run the project to compile SQL and execute on your warehouse
pb run
rudder-profiles --version
Debug
Known issues
breakingUpgrading to new versions might require manual uninstallation and reinstallation of associated libraries like `profiles-pycorelib` to resolve dependency conflicts.fixExecute `pip3 uninstall profiles-pycorelib; pip3 uninstall profiles-rudderstack; pip3 install profiles-rudderstack --no-cache-dir` to perform a clean reinstall.
affects: <=0.11.0 to recent
gotchaThe 'pb' command might not be recognized after installation, especially on Windows or if Python paths are not correctly configured.fixRestart your terminal/shell. If the issue persists, verify Python 3 is installed correctly, ensure `pip` is in your PATH, or explicitly navigate to the `profiles-rudderstack` installation's `/bin` subdirectory.
affects: All versions
gotchaWarehouse connection requires specific read/write permissions to source data schemas and the target schema for Profiles outputs. Insufficient permissions will lead to runtime errors.fixEnsure the user account used for connection has read access to input tables and write access to the output schema. For Snowflake, a generic role like `PROFILES_ROLE` with appropriate privileges is recommended.
affects: All versions
gotchaCross-database references can fail on some Redshift clusters, and `pb insert` functionality is not supported for Redshift, Databricks, and BigQuery.fixBe aware of these limitations when designing projects for these warehouses. For Redshift, avoid cross-database references or test thoroughly. Use alternative methods for data insertion if `pb insert` is critical.
affects: All versions
gotchaLinux users might encounter a `DBUS_SESSION_BUS_ADDRESS` warning during command runs, which can usually be ignored.fixSet the `DBUS_SESSION_BUS_ADDRESS` environment variable to `$XDG_RUNTIME_DIR/bus` (if it exists) or `/dev/null` to suppress the warning.
affects: All versions
Upgrade
Version history
0.25.6latest on PyPI · released Jun 4, 2026
Audit
Dependencies
profiles-pycorelibrequiredRequired for core functionality, ensure compatibility during upgrades.
profiles-mlcoreliboptionalRequired for ML-related features if used.
uvoptionalUsed by setup script for package management.