pyproject.toml Reference

Use pyproject.toml to define one or more fal apps in a project. Each entry in [tool.fal.apps] gives an app a stable local name that you can pass to fal run or fal deploy instead of repeating a file path and class reference.

[tool.fal.apps]
image-generator = { ref = "src/app.py::ImageGenerator", auth = "private", machine_type = "GPU-H100" }

fal run image-generator
fal deploy image-generator

App paths are resolved from the directory that contains pyproject.toml.

fal deploy respects auth from pyproject.toml. fal run currently defaults to public auth and only changes auth mode when you pass --auth.

Package Entry Points

Use python_entry_point when your fal app is importable as a Python package and you want fal to load it by module path:

[project]
name = "my-image-app"
version = "0.1.0"
dependencies = ["fal"]

[tool.fal.apps]
image-generator = {
  python_entry_point = "my_image_app.server:ImageGenerator",
  requirements = ["."],
  auth = "private",
  machine_type = "GPU-H100"
}

python_entry_point must use <module>:<symbol> format. It is mutually exclusive with ref. Runtime and deployment settings for entry-point apps are read from pyproject.toml, not from class attributes or function decorator options in the imported package. For packaging requirements, monorepo examples, and custom-container usage, see Package Entry Points.

Multiple Apps

Define multiple apps in the same project by using app-specific tables:

[tool.fal.apps.image-generator]
ref = "src/image_app.py::ImageGenerator"
auth = "private"
machine_type = "GPU-H100"

[tool.fal.apps.captioner]
python_entry_point = "my_package.captioner:Captioner"
requirements = ["."]
auth = "shared"
machine_type = "GPU-A100"

Deploy each app by its key:

fal deploy image-generator
fal deploy captioner

App Fields

Field	Type	Description
`ref`	`string`	File reference to load, such as `src/app.py::MyApp`. Mutually exclusive with `python_entry_point`. Required unless `python_entry_point` or image-only container config is used.
`python_entry_point`	`string`	Import path in `<module>:<symbol>` format. Use with `requirements = ["."]` or with a container image that already includes the package. Mutually exclusive with `ref`.
`name`	`string`	Deployed app name. Defaults to the `[tool.fal.apps]` key.
`auth`	`string`	Authentication mode: `private`, `public`, or `shared`.
`team`	`string`	Team slug to use when running or deploying this app. A CLI `--team` value overrides it.
`deployment_strategy`	`string`	Deploy strategy: `rolling` or `recreate`.
`app_scale_settings`	`boolean`	When `true`, deploys with the scale settings from this config instead of inheriting runtime-tuned settings from the previous deployment.
`requirements`	`list[string]` or `list[list[string]]`	Pip requirements. `.`, `.[extra]`, and `projects/foo[extra]` package a local project before installing it on the runner.
`requirements_context_dir`	`string`	Base directory for resolving local-path `requirements`. Relative paths resolve from the `pyproject.toml` directory.
`python_version`	`string`	Python version for the runtime, such as `"3.12"`.
`machine_type`	`string` or `list[string]`	Machine type or fallback list, such as `"GPU-H100"` or `["GPU-H100", "GPU-A100"]`.
`num_gpus`	`integer`	Number of GPUs to allocate for GPU machine types.
`regions`	`list[string]`	Allowed regions. Supported values are `us-west`, `us-central`, `us-east`, `eu-north`, and `eu-west`.
`min_concurrency`	`integer`	Minimum warm runners.
`max_concurrency`	`integer`	Maximum runners to scale to.
`max_multiplexing`	`integer`	Maximum concurrent requests per runner.
`concurrency_buffer`	`integer`	Additional runners to keep warm above current load.
`concurrency_buffer_perc`	`integer`	Percentage buffer of runners above current load.
`scaling_delay`	`integer`	Seconds to wait before scaling up for pending requests.
`keep_alive`	`integer`	Seconds to keep an idle runner alive.
`request_timeout`	`integer`	Maximum seconds for a single request.
`startup_timeout`	`integer`	Maximum seconds for runner startup and `setup()`.
`private_logs`	`boolean`	Restrict app logs to the owning account or team.
`app_files`	`list[string]`	Local files or directories to include with the app. Not supported for container apps.
`app_files_ignore`	`list[string]`	Regex patterns to exclude from `app_files`.
`app_files_context_dir`	`string`	Base directory for resolving `app_files`. Only valid when `app_files` is set. Relative paths resolve from the `pyproject.toml` directory.
`exposed_port`	`integer`	HTTP port exposed by a custom server app.
`skip_retry_conditions`	`list[string]`	Retry conditions to skip. Supported values include `timeout`, `server_error`, and `connection_error`.
`retry_config`	`table`	Default retry budget per retry condition, e.g. `{ server_error = { retries = 3 } }`. See Retries and Error Handling.
`termination_grace_period_seconds`	`integer`	Grace period for runner shutdown.
`secrets`	`list[string]`	Runtime fal secrets to mount into the app environment.
`data_mounts`	`list[string]`	Persistent data paths to mount.
`health_check`	`table`	Health check configuration. See Health Check.
`image`	`table`	Container image configuration. See Container Image.

no_scale is deprecated. Use app_scale_settings instead.

Health Check

[tool.fal.apps.image-generator.health_check]
path = "/health"
start_period_seconds = 30
timeout_seconds = 5
failure_threshold = 3
call_regularly = true

Field	Type	Description
`path`	`string`	Required health check endpoint path.
`start_period_seconds`	`integer`	Minimum runner age before failures count as unhealthy.
`timeout_seconds`	`integer`	Timeout for each health check request.
`failure_threshold`	`integer`	Consecutive failures before the runner is marked unhealthy.
`call_regularly`	`boolean`	Whether fal should call the health check periodically.

Container Image

Use the [tool.fal.apps.<app-name>.image] section to configure a container from pyproject.toml. Build from a Dockerfile:

[tool.fal.apps.container-app]
python_entry_point = "my_package.app:MyApp"
machine_type = "GPU-H100"

[tool.fal.apps.container-app.image]
dockerfile = "Dockerfile"
build_args = { CUDA_VERSION = "12.4" }
entrypoint = ["python", "-m", "my_package.app"]
cmd = ["--host", "0.0.0.0", "--port", "8080"]
secrets = { PIP_TOKEN = "$PIP_TOKEN" }

Or reference an existing image:

[tool.fal.apps.container-app]
machine_type = "GPU-H100"
exposed_port = 8000

[tool.fal.apps.container-app.image]
image = "my-org/container-app:latest"
cmd = ["your-server", "--host", "0.0.0.0", "--port", "8000"]

[tool.fal.apps.container-app.image.registries."https://index.docker.io/v1/"]
username = "myuser"
password = "$DOCKERHUB_TOKEN"

Field	Type	Description
`dockerfile`	`string`	Path to the Dockerfile. Relative paths resolve from the `pyproject.toml` directory. Mutually exclusive with `image`.
`image`	`string`	Existing container image reference, such as `my-org/container-app:latest`. Mutually exclusive with `dockerfile`.
`build_args`	`table`	Docker build arguments. Only valid with `dockerfile`.
`registries`	`table`	Private registry credentials for Dockerfile base images or referenced images.
`secrets`	`table`	Build-time secrets. Values prefixed with `$` resolve from fal secrets. Only valid with `dockerfile`.
`entrypoint`	`string` or `list[string]`	Docker ENTRYPOINT override.
`cmd`	`string` or `list[string]`	Docker CMD override.

Set either dockerfile or image under [tool.fal.apps.<app-name>.image]. Use registries when the Dockerfile pulls a private base image or when image references a private image. Container apps can use ref, python_entry_point, or neither. If both ref and python_entry_point are omitted, fal treats the container as an image-only app and does not use the fal Python app loader. When a container app uses python_entry_point, make sure the Dockerfile or existing image installs the package that contains the referenced module.

Client Libraries

CLI Reference

Python SDK

pyproject.toml Reference

Package Entry Points

Multiple Apps

App Fields

Health Check

Container Image

​Package Entry Points

​Multiple Apps

​App Fields

​Health Check

​Container Image

Package Entry Points

Multiple Apps

App Fields

Health Check

Container Image