Streamlit / Altair Dependency Error

Quick Start Job Aid · Palantir Foundry Environment

1. The Error

When running streamlit run streamlitapp.py in a Foundry Code Workspace, the following traceback appeared:

ModuleNotFoundError: No module named 'altair.vegalite.v4'

Root Cause

Streamlit 1.x expects Altair v4 (which uses the altair.vegalite.v4 module path). However, the environment had Altair v5+ installed, which restructured its internal module layout — breaking the import. A secondary conflict was also present:

streamlit 1.54.0 requires pandas<3, but pandas 3.0.1 was installed

Both issues stemmed from unpinned dependencies in the environment manifest, allowing newer incompatible versions to be resolved.

2. Step-by-Step Fix (Palantir Foundry)

Step 1 — Identify the manifest file

In Palantir Foundry Code Workspaces, packages are managed through a meta.yaml manifest, NOT directly via pip. The file is hidden by default.

• In JupyterLab, go to View > Show Hidden Files
• Navigate to .envs/maestro/meta.yaml

Step 2 — Edit meta.yaml

Locate the pip: section and add version pins for the conflicting packages:

requirements:

run:

- streamlit

- pandas

pip:

- protobuf<3.21

- setuptools<80.0.0

- altair>=4,<5 # Fix for altair.vegalite.v4 error

- pandas>=1.4.0,<3 # Fix for pandas version conflict

Step 3 — Reinstall the environment

Run the following command in the Foundry terminal. No arguments are needed — Maestro reads meta.yaml automatically:

maestro env install

Step 4 — Verify the fix

streamlit run streamlitapp.py

The app should now launch without the Altair import error.

3. Foundry vs. Local vs. Other Environments

Debugging Python dependency issues in Palantir Foundry requires a different workflow compared to local development or other cloud environments. The table below summarizes the key differences:

Foundry-Specific Gotchas

• pip install does not work directly — Maestro intercepts it and may error on unrecognized flags like --upgrade
• Maestro install syntax differs — package names go in meta.yaml, not on the command line
• Two sections in meta.yaml control packages: run: (conda packages) and pip: (pip-only packages). Version pins typically go in pip:
• Dependency conflicts may only surface after install completes — check the full Maestro output for WARNING or ERROR lines even on apparent success
• Workspace restarts may be required after environment changes before the new packages are active

Local / Standard Environment

• pip install 'altair>=4,<5' works directly in the terminal
• pip install --upgrade streamlit upgrades to a version with Altair v5 support
• Virtual environments (venv / conda) are managed per-project, not platform-wide
• requirements.txt or environment.yml hold version pins; regenerate with pip freeze > requirements.txt

Docker / CI Environments

• Version pins belong in requirements.txt or Dockerfile RUN commands
• Rebuild the container image after changing dependencies
• Use multi-stage builds to keep dependency resolution separate from the app layer

4. Quick Reference — Maestro Commands

5. Preventing Future Dependency Conflicts

• Always pin both the upper and lower bounds for sensitive packages: altair>=4,<5 not just altair
• After adding any new package, check Maestro output for dependency conflict warnings and pin accordingly
• Keep a record of known-compatible version combinations for your Streamlit version
• When upgrading Streamlit, review its release notes for changes to Altair, pandas, and protobuf requirements before updating meta.yaml