Skip to main content
The fal package provides decorators and utilities for building serverless AI applications.

​
Installation

pip install fal

​
Quick Start

import fal

class MyApp(fal.App):
    @fal.endpoint("/")
    def run(self) -> dict:
        return {"message": "Hello, World!"}
Deploy with: 
fal deploy my_app.py
See the Quick Start guide for a complete walkthrough.

​
API Reference

fal

App class, decorators (endpoint, realtime, function, cached), HealthCheck, ContainerImage

fal.api

SyncServerlessClient: manage apps, runners, keys, secrets, and deploy programmatically

fal.toolkit

File types (Image, Video, Audio), KVStore, model downloads, GPU utilities

fal.exceptions

Exception classes for error handling

CLI

fal deploy, fal apps, fal runners, fal keys, fal secrets, and more

​
Key Decorators

DecoratorDescription
@fal.endpoint(path)Define an HTTP endpoint on an App
@fal.realtime(path)WebSocket endpoint for realtime applications
@fal.function(...)Create a standalone serverless function
@fal.cachedCache function results in-memory
See the fal module reference for full details.

​
App Configuration

Configure your app using class variables. See the full App reference for all options.
PropertyDescription
machine_typeGPU type: "GPU", "A100", or list for fallback
requirementsPip packages to install (e.g., ["torch>=2.0"])
num_gpusNumber of GPUs to allocate
min_concurrencyMinimum warm instances (1+ to avoid cold starts)
max_concurrencyMaximum instances to scale to
request_timeoutMaximum seconds per request
startup_timeoutMaximum seconds for setup
app_authAuth mode: "private", "public", or "shared"
app_filesFiles/directories to include in deployment
imageCustom ContainerImage for the application

​
Toolkit Highlights

The fal.toolkit module provides utilities for common tasks:
UtilityDescription
Image, Video, AudioFile types with automatic CDN upload
KVStorePersistent key-value storage
download_model_weights()Download and cache model weights
clone_repository()Clone git repositories
sync_dir()Sync local directories to remote storage
get_gpu_type()Detect current GPU type

​
SyncServerlessClient

The SyncServerlessClient provides programmatic access to fal operations (mirrors the CLI): 
from fal.api import SyncServerlessClient

client = SyncServerlessClient()

# Manage apps
apps = client.apps.list()
client.apps.scale("my-app", max_concurrency=10)

# Manage runners
runners = client.runners.list()
client.runners.stop("runner-id")

# Manage keys and secrets
client.keys.create(scope="admin")
client.secrets.set("API_KEY", "value")

# Deploy
client.deploy("path/to/app.py::MyApp")
For detailed guides on building applications, see the Serverless documentation.