build

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.

flash build [OPTIONS]

Examples

Build with all dependencies:

flash build

Build with additional excluded packages:

flash build --exclude scipy,pandas

Build with custom output name:

flash build -o my-app.tar.gz

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 · default: "3.12"

Target Python version for worker images (3.10, 3.11, or 3.12). Overrides per-resource python_version declarations. Defaults to the version declared on resource configs, or 3.12 if none set.

What happens during build

1. Python version resolution: Resolves the target Python version from CLI flag, resource configs, or default (3.12).
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. Dependency installation: Installs Python packages for Linux x86_64.
6. 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.

Category	Patterns
Build artifacts	.build/, .flash/, .runpod/, *.tar.gz, .git/, __pycache__/, *.pyc, *.pyo, *.pyd, *.egg-info/, dist/, build/
Virtual environments	.venv/, venv/, env/
IDE files	.vscode/, .idea/
Environment files	.env, .env.local
Tests	tests/, test_*.py, *_test.py
Documentation	docs/, *.md (except README.md)

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:

File/Directory	Description
.flash/artifact.tar.gz	Deployment package ready for Runpod
.flash/flash_manifest.json	Service discovery configuration
.flash/.build/	Build directory (kept for inspection)

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, and 3.12. 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. Default: Python 3.12 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.

Version	Cold start	Notes
3.12 (default)	No overhead	PyTorch pre-installed in base image
3.11	+~7 GB on GPU	Alternative Python install required
3.10	+~7 GB on GPU	EOL 2026-10-31; consider migrating to 3.11

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:

flash build --exclude scipy,pandas

Base image reference

Resource type	Base image	Auto-excluded packages
GPU	PyTorch base	torch, torchvision, torchaudio, triton
CPU	Python slim	torch, torchvision, torchaudio, triton

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:

from runpod_flash import Endpoint, GpuGroup

@Endpoint(name="my-worker", gpu=GpuGroup.ANY)
def my_function(data):
    return {"result": data}

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:

flash build --exclude scipy,pandas

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:

ls .flash/.build/

Related commands

• flash deploy - Build and deploy in one step (includes --preview option for local testing)
• flash run - 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.