fal

library1.76.0pypypi✓ verified 87d ago

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.

devops ai-ml aws

pip install fal

package ↗homepage ↗

INSTALL

IMPORT

SIG · FAL

fal

devopspythonv1.76.0

Install

10.0s avg

Import

2671ms

Disk

120MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.76.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.940 runs

installs and imports cleanly · install 0.0s · import 2.944s · 75MB

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 10.0s · import 2.398s · 162MB

120MB installed

● package 120MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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

fal --version

Debug

Known issues

gotchaThe `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.

affects: All versions

gotchaAuthentication 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.

affects: All versions

breakingStarting 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.

affects: >=1.61.0

gotchaWhen 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.

affects: All versions

gotchaThe 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.

affects: Versions released after Oct 2025 (approximately >=1.60.0)

Errors

Common errors & fixes

fal: command not found

The Fal CLI (Command Line Interface) is not installed on your system or is not included in your system's PATH environment variable.

fix

Install the Fal CLI using pip: `pip install fal`. If already installed, ensure your system's PATH includes the directory where pip installs executables.

"Authentication is required to access this application." or "invalid key credentials"

The Fal CLI or client SDK cannot authenticate with the Fal platform. This is typically due to a missing, incorrect, expired, or improperly scoped API key, or the user has not logged in via the CLI.

fix

Authenticate interactively using `fal auth login` in your terminal. Alternatively, set your API key as an environment variable: `export FAL_KEY="your-api-key-here"` (replace with your actual API key from the Fal dashboard).

ModuleNotFoundError: No module named 'fal'

The `fal` Python package (or `fal-client` if that's the specific import) is not installed in your active Python environment.

fix

Install the necessary Fal Python package using pip: `pip install fal` or `pip install fal-client` if you are only using the client SDK.

Command '['pip', 'install', '-r', 'requirements.txt']' returned non-zero exit status X.

During deployment, Fal attempts to install the dependencies listed in your `requirements.txt` file, and one or more packages failed to install, often due to incorrect package names, incompatible versions, or missing build dependencies for certain packages.

fix

Carefully review your `requirements.txt` file for typos, ensure all package versions are compatible and explicitly pinned (e.g., `package==1.0.0`), and verify that all specified packages are available on PyPI or the specified alternative index.

Upgrade

Version history

1.76.0latest on PyPI · released Jun 12, 2026

Audit

Dependencies

fal-clientoptionalUsed for calling fal Model APIs or your own deployed fal apps from Python code.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/fal/ ↗

homepagehttps://fal.ai ↗