build - Runpod Documentation

The Flash CLI is now part of the rp CLI that ships with the Runpod SDK. This page documents the standalone flash command from the runpod-flash package, which stops getting fixes and updates after its deprecation date. For new projects, use the rp CLI. To see how flash commands map to rp flash, see Migrating from Flash.

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

Skip transitive dependencies during pip install. Only installs direct dependencies specified in @Endpoint decorators. Useful when the base image already includes dependencies.

string

default:"artifact.tar.gz"

Custom name for the output archive file.

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.

string

Target Python version for worker images (3.10, 3.11, 3.12, or 3.13). Defaults to the python_version declared on your resource configs, or 3.12 if none declares one. The build fails if the flag conflicts with a declared python_version.

What happens during build

Function discovery: Finds all @Endpoint decorated functions.
Grouping: Groups functions by their endpoint configuration.
Python version resolution: Resolves the target Python version from the CLI flag, resource configs, or the 3.12 default.
Manifest generation: Creates .flash/flash_manifest.json with endpoint definitions.
Source fingerprinting: Computes a SHA-256 fingerprint of your source files to detect code changes between deployments.
Dependency installation: Installs Python packages for Linux x86_64.
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.

Local modules and the ignore filter

Local (non-pip) modules that your endpoints import are bundled automatically, provided they pass the ignore filter: your .gitignore plus the built-in patterns listed above. During the build, Flash resolves the transitive local-import closure of every shipped Python file and checks it against the files the ignore filter already selected. If shipped code imports a local module that an ignore rule excludes (for example, a test_*.py sibling or a file under tests/), the build fails with a LocalModuleResolutionError instead of silently overriding your ignore rules or shipping a broken artifact. Flash names each excluded file and the file that imports it:

Shipped code imports local modules that the build ignore rules (.gitignore or built-in defaults) exclude:
  utils/helpers.py (imported by endpoint.py)

Shipping them would silently override a deliberate exclusion, and omitting them would break the worker with ModuleNotFoundError. Remove the matching ignore pattern or stop importing these modules from shipped code.

If an @Endpoint file has a local import Flash can’t resolve at all (a broken relative import, or a file outside your project root), the build also fails with a clear error. A file that fails resolution but doesn’t define an endpoint is skipped with a warning and the build continues. For details on how local imports are resolved and bundled, see Import local modules.

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, 3.12, and 3.13. Your local Python version doesn’t change the worker version. Flash picks the worker version in this order:

CLI flag: --python-version.
Resource config: the python_version field on a resource config class such as LiveServerless. The @Endpoint decorator has no python_version parameter.
Default: Python 3.12.

All endpoints in an app use the same version because Flash ships a single tarball for the entire app. The build fails if resources declare different versions, or if --python-version conflicts with a version a resource declares.

Version	Cold start	Notes
3.12	No overhead	PyTorch pre-installed in base image
3.13	+~7 GB on GPU	PyTorch reinstalled for this interpreter
3.11	+~7 GB on GPU	PyTorch reinstalled for this interpreter
3.10	+~7 GB on GPU	EOL 2026-10-31; consider migrating to 3.11+

You can run flash build from any local Python version from 3.10 to 3.14. Flash downloads dependency wheels for the worker’s Python version, not your local one. 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 leaves these packages out of the archive because the GPU worker images provide them:

torch, torchvision, torchaudio, triton

You don’t need to exclude them manually. CPU worker images don’t include them, so code on CPU workers can’t import these packages.

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 Flash worker 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:

Ensure standard pip is installed: python -m ensurepip --upgrade
Check PyPI for Linux wheel availability.

Need to examine generated files

The build directory is kept after building. Inspect it with:

ls .flash/.build/

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.

​Examples

​Flags

​What happens during build

​Built-in ignore patterns

​Local modules and the ignore filter

​Build artifacts

​Cross-platform builds

​Python version in deployed workers

​Managing deployment size

​Manual exclusions

​Base image reference

​Troubleshooting

​Build fails with “functions not found”

​Archive is too large

​Dependency installation fails

​Need to examine generated files

​Related commands

Examples

Flags

What happens during build

Built-in ignore patterns

Local modules and the ignore filter

Build artifacts

Cross-platform builds

Python version in deployed workers

Managing deployment size

Manual exclusions

Base image reference

Troubleshooting

Build fails with “functions not found”

Archive is too large

Dependency installation fails

Need to examine generated files

Related commands