Python SDK

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

Decorator	Description
`@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.cached`	Cache 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.

Property	Description
`machine_type`	GPU type: `"GPU-A100"`, `"GPU-H100"`, or list for fallback (see Machine Types)
`requirements`	Pip packages to install (e.g., `["torch>=2.0"]`)
`requirements_context_dir`	Base directory for resolving local-path requirements such as `.[extra]` or `projects/foo[extra]`
`num_gpus`	Number of GPUs to allocate
`min_concurrency`	Minimum warm instances (1+ to avoid cold starts)
`max_concurrency`	Maximum instances to scale to
`request_timeout`	Maximum seconds per request
`startup_timeout`	Maximum seconds for setup
`app_auth`	Auth mode: `"private"`, `"public"`, or `"shared"`
`app_files`	Files/directories to include in deployment
`image`	Custom `ContainerImage` for the application

Toolkit Highlights

The fal.toolkit module provides utilities for common tasks:

Utility	Description
`Image`, `Video`, `Audio`	File types with automatic CDN upload
`KVStore`	Persistent 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.

Client Libraries

CLI Reference

Python SDK

Python SDK

Installation

Quick Start

API Reference

fal

fal.api

fal.toolkit

fal.exceptions

CLI

Key Decorators

App Configuration

Toolkit Highlights

SyncServerlessClient

​Installation

​Quick Start

​API Reference

fal

fal.api

fal.toolkit

fal.exceptions

CLI

​Key Decorators

​App Configuration

​Toolkit Highlights

​SyncServerlessClient

Installation

Quick Start

API Reference

Key Decorators

App Configuration

Toolkit Highlights

SyncServerlessClient