Skip to main content
Build a deployment-ready artifact for your Flash application without deploying. Use this for more control over the build process or to inspect the artifact before deploying.

​
Examples

Build with all dependencies:
Build with additional excluded packages:
Build with custom output name:

​
Flags

​
--no-deps
Skip transitive dependencies during pip install. Only installs direct dependencies specified in @Endpoint decorators. Useful when the base image already includes dependencies.
​
--output, -o
string
default:"artifact.tar.gz"
Custom name for the output archive file.
​
--exclude
string
Comma-separated list of packages to exclude from the build (e.g., torch,torchvision). Use this to skip packages already in the base image.
​
--python-version
string
Target Python version for worker images (3.10, 3.11, 3.12, or 3.13). Overrides per-resource python_version declarations and local interpreter detection.

​
What happens during build

  1. Python version resolution: Resolves the target Python version from CLI flag, resource configs, or your local interpreter.
  2. Function discovery: Finds all @Endpoint decorated functions.
  3. Grouping: Groups functions by their endpoint configuration.
  4. Manifest generation: Creates .flash/flash_manifest.json with endpoint definitions.
  5. Source fingerprinting: Computes a SHA-256 fingerprint of your source files to detect code changes between deployments.
  6. Dependency installation: Installs Python packages for Linux x86_64.
  7. Packaging: Bundles everything into .flash/artifact.tar.gz.

​
Built-in ignore patterns

Flash automatically excludes certain files and directories from deployment artifacts. These patterns cover common development files that shouldn’t be deployed to production. Flash also respects your .gitignore file and excludes any files matching those patterns.
If you use other environment file variants like .env.dev or .env.staging, add them to your .gitignore to exclude them from deployment artifacts.

​
Build artifacts

After running flash build:

​
Cross-platform builds

Flash automatically handles cross-platform builds:
  • Automatic platform targeting: Dependencies are installed for Linux x86_64, regardless of your build platform.
  • Binary wheel enforcement: Only pre-built wheels are used, preventing compilation issues.

​
Python version in deployed workers

Flash workers support Python 3.10, 3.11, 3.12, and 3.13. The target version is determined by:
  1. CLI flag: The --python-version flag takes precedence.
  2. Resource config: The python_version parameter on your endpoint configs.
  3. Local interpreter: Your local Python version (from sys.version_info) when neither is specified.
All resources in a Flash app must use the same Python version because Flash ships a single tarball for the entire app. If resources declare conflicting versions, the build fails.
Breaking change in Flash 0.x: Flash now matches your local Python version by default instead of always defaulting to Python 3.12. If you upgrade Flash and your local Python differs from 3.12, your first deploy will trigger a rolling release. To maintain consistent behavior across team members, declare python_version explicitly on your resource configs or use --python-version on the CLI.
If your local Python version is not supported (for example, 3.9 or 3.14), the build fails with an actionable error message listing the supported versions. Image tags follow the pattern py{version}-{tag} (for example, runpod/flash:py3.12-latest).

​
Managing deployment size

Runpod Serverless has a 1.5GB deployment limit. Flash automatically excludes packages that are pre-installed in the base image:
  • torch, torchvision, torchaudio, triton
These packages are excluded at archive time, so you don’t need to specify them manually.

​
Manual exclusions

Use --exclude to skip additional packages that are already in a custom base image or not needed:

​
Base image reference

Check the worker-flash repository for current base images and pre-installed packages.

​
Troubleshooting

​
Build fails with “functions not found”

Ensure your project has @Endpoint decorated functions:

​
Archive is too large

Some CUDA packages (torch, torchvision, torchaudio, triton) are auto-excluded. If the archive is still too large, use --exclude to skip additional packages or --no-deps to skip transitive dependencies:

​
Dependency installation fails

If a package doesn’t have Linux x86_64 wheels:
  1. Ensure standard pip is installed: python -m ensurepip --upgrade
  2. Check PyPI for Linux wheel availability.

​
Need to examine generated files

The build directory is kept after building. Inspect it with:
  • flash deploy - Build and deploy in one step (includes --preview option for local testing)
  • flash dev - Start development server
  • flash env - Manage environments
Most users should use flash deploy instead, which runs build and deploy in one step. Use flash build when you need more control or want to inspect the artifact.