fal: Serverless Python Framework

1.72.1 · active · verified Wed Apr 15

fal is an easy-to-use Serverless Python Framework that enables developers to build, test, and deploy serverless applications and machine learning models on GPU-accelerated infrastructure. It offers a Python SDK for defining applications and a CLI for deployment and management. The library is actively maintained, with frequent releases, and is currently at version 1.72.1.

Warnings

gotcha The `fal` package (for building/deploying apps) and `fal-client` package (for calling models/endpoints) are distinct. Ensure you install and import the correct one for your use case.
Fix: Use `pip install fal` for app development/deployment, `pip install fal-client` for calling APIs. Import `fal` for app definition and `fal_client` for client interactions.
gotcha Authentication is crucial. For development and deployment, use `fal auth login` via the CLI. For programmatic client calls, the `fal-client` library typically expects the `FAL_KEY` environment variable to be set, or it can be passed explicitly.
Fix: Run `fal auth login` in your terminal. For client SDK usage, ensure `export FAL_KEY="your-api-key-here"` is set in your environment or provide `api_key` argument to client constructors.
breaking Starting with `fal>=1.61.0`, runners now receive a `SIGTERM` signal with a 5-second grace period before `SIGKILL` when terminated. This affects app cleanup during shutdown.
Fix: Implement a `teardown()` method in your `fal.App` class to handle graceful cleanup within the 5-second grace period.
gotcha When running apps locally with `fal run`, the default authentication mode is `public`. If you require API key authentication during local development, explicitly use the `--auth private` flag.
Fix: Execute `fal run your_app.py::MyApp --auth private` to enforce private authentication during local testing.
gotcha The runner state model was updated around October 2025 to include an `IDLE` state. If you are programmatically monitoring or tracking runner states, your integrations might need updates.
Fix: Update any integrations that consume runner state information to correctly handle the new `IDLE` state. Refer to the 'Understanding Runners' guide in the fal documentation.

Install

pip install fal Install fal for app development and deployment
pip install fal-client Install fal-client for consuming models and endpoints

Imports

fal
```
import fal
```
Used for defining serverless applications with fal.App and decorators.
fal_client
```
import fal_client
```
Used for interacting with deployed fal models or applications as a client.
SyncServerlessClient
```
from fal.api import SyncServerlessClient
```
Used for programmatic management of fal apps, runners, keys, and secrets without the CLI or async/await. Introduced around October 2025.

Quickstart

This quickstart demonstrates defining a simple 'Hello World' serverless application using `fal.App` and the `@fal.endpoint` decorator. It highlights the basic structure for a deployable application. Local testing and deployment are typically handled via the `fal` CLI after installing the `fal` package and authenticating.

import fal
import os

# Ensure FAL_KEY is set as an environment variable (e.g., export FAL_KEY="YOUR_API_KEY")
# or authenticate via 'fal auth login' CLI command.
fal_key = os.environ.get('FAL_KEY', '')
if not fal_key:
    print("Warning: FAL_KEY environment variable not set. Please authenticate via 'fal auth login' or set FAL_KEY.")

class HelloApp(fal.App):
    @fal.endpoint("/")
    def run(self) -> dict:
        print("Processing Hello World request...")
        return {"message": "Hello, World!"}

# To run locally for testing (requires fal CLI and authentication):
# fal run your_app_file.py::HelloApp

# To deploy to a persistent endpoint:
# fal deploy your_app_file.py::HelloApp

view raw JSON →