#422 Build: Docker layer granularity optimization plan Pull request opened by yuhuan130 ## Summary Explore improving Docker build cache efficiency by separating layers based on how frequently they change. ## Problem Some Docker layers currently mix dependencies with very different change frequencies. This causes unnecessary cache invalidation and slower rebuilds during development. ## Proposed direction Order layers from most stable → most frequently changing: 1. System packages (apt) 2. Base Python dependencies 3. Project / feature dependencies 4. Local source code This should allow common code-only changes to rebuild only the final layer. ## Example (illustrative) # Less cache-friendly Image.from_debian_base().with_pip_packages( "pandas", "numpy", "scikit-learn", "matplotlib", "jupyter", "requests" ) # More cache-friendly ( Image.from_debian_base() .with_pip_packages("pandas", "numpy", "requests") .with_pip_packages("scikit-learn") .with_pip_packages("matplotlib", "jupyter") ) Before (Cache-Unfriendly): ┌────────────────────────────────────────┐ │ UVScript: Script + All Dependencies │ ← Any change rebuilds everything │ (pandas + matplotlib + jupyter + code) │ └────────────────────────────────────────┘ After (Cache-Friendly with Auto-Separation): ┌────────────────────────────────────────┐ │ UVScript: Script only (Optional) │ ← Highest churn ├────────────────────────────────────────┤ │ Layer 4 (dev): jupyterlab, ruff, … │ ← Freq: High | Cost: Low ├────────────────────────────────────────┤ │ Layer 3 (viz): matplotlib, plotly, … │ ← Freq: Med | Cost: Low ├────────────────────────────────────────┤ │ Layer 2 (utils): httpx, boto3, … │ ← Freq: Med | Cost: Low ├────────────────────────────────────────┤ │ Layer 1 (core_data): numpy, pandas… │ ← Freq: Low | Cost: Med ├────────────────────────────────────────┤ │ Layer 0 (heavy_ml): torch, tensorflow… │ ← Freq: Very Low | Cost: High ├────────────────────────────────────────┤ │ Base layers (Python + System) │ ← Rarely change └────────────────────────────────────────┘ ## Docker Layering Tradeoff We intentionally structured dependency layers by build cost and change frequency. • Heavy frameworks (e.g. TensorFlow, PyTorch, Flyte) are isolated in low-churn layers to avoid expensive rebuilds. • Faster-changing tooling and visualization libraries are kept higher to preserve iteration speed. • This trades a slightly larger image context for significantly faster rebuilds during ML development and training. Net effect: lower developer wait time, predictable builds, and better scalability as pipelines grow. ## Real-time examples tensorflow + optimization [Screenshot 2025-12-14 at 16 28 28](https://private-user-images.githubusercontent.com/115371007/526267349-64bd602c-e8e3-470e-81f8-27d7e7a4d6b0.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NjU3MDE2MDIsIm5iZiI6MTc2NTcwMTMwMiwicGF0aCI6Ii8xMTUzNzEwMDcvNTI2MjY3MzQ5LTY0YmQ2MDJjLWU4ZTMtNDcwZS04MWY4LTI3ZDdlN2E0ZDZiMC5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjUxMjE0JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI1MTIxNFQwODM1MDJaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT1iYjAyNDlmOTJhNTlhZDU4YzM0NjkxNmUxMmNjZTNjMGE3MDA5MmZhZDM3ZGMxYWE5ZTkxYTQ2ZmUwMGNiOGUwJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.wzTiv5rjACvJg8FZu2Ihq9aC5Fz9p6Gubymv6oQEC-c) tensorflow + mypy + optimization [Screenshot 2025-12-14 at 16 28 44](https://private-user-images.githubusercontent.com/115371007/526267352-e7ed3b8a-0eb9-4ee0-af0d-3cf2c4d2fc20.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NjU3MDE2MDIsIm5iZiI6MTc2NTcwMTMwMiwicGF0aCI6Ii8xMTUzNzEwMDcvNTI2MjY3MzUyLWU3ZWQzYjhhLTBlYjktNGVlMC1hZjBkLTNjZjJjNGQyZmMyMC5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjUxMjE0JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI1MTIxNFQwODM1MDJaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT1iMDZhNmIxNjViOWRmNGU2MWRhMGYzMzQyMDI0NzczNTliZjU3NjE1NmJiZmNmOWViNDc4NjBjMDUwY2IwMzQwJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.MfIiB5URe4G5DDkGka7IxO5KPJ0mX_mk9I6RxGPhSAA) tensorflow [Screenshot 2025-12-14 at 16 28 57](https://private-user-images.githubusercontent.com/115371007/526267356-46dfeaff-5f6c-4dfe-9cec-7fd5098f0f63.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NjU3MDE2MDIsIm5iZiI6MTc2NTcwMTMwMiwicGF0aCI6Ii8xMTUzNzEwMDcvNTI2MjY3MzU2LTQ2ZGZlYWZmLTVmNmMtNGRmZS05Y2VjLTdmZDUwOThmMGY2My5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjUxMjE0JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI1MTIxNFQwODM1MDJaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT05YmJkOTBhMjk2OTY4OGM3ZWJkZDE1YTg3NDQyOTUwODlkMTIwZGY4MDI1ZDgyYzMyNmI1NjZiZmY3MjNhZWFiJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9._UJMHatNC2-8Yc2DJcouSQlVkx73mA9nT9JufcGX5MY) tensorflow + mypy <https://private-user-images.githubusercontent.com/115371007/526267357-2fa8b0c0-b6d5-4f8e-9deb-24f31fbde328.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NjU3MDE2MDIsIm5iZiI6MTc2NTcwMTMwMiwicGF0aCI6Ii8xMTUzNzEwMDcvNTI2MjY3MzU3LTJmYThiMGMwLWI2ZDUtNGY4ZS05ZGViLTI0ZjMxZmJkZTMyOC5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUy… flyteorg/flyte-sdk