Skip to main content
Functions are the basic units of serverless execution on Modal. Generally, you will not construct a Function directly. Instead, use the @app.function() decorator to register your Python functions with your App.

​
Properties

​
function.web_url

function.web_url -> Optional[str]
URL of the web endpoint for this function, if it’s a web endpoint.

​
Methods

​
function.remote

function.remote(*args, **kwargs) -> Any
Call the function remotely and return the result. This is a blocking call that waits for the function to complete and returns its result. Example: 
@app.function()
def my_function(x: int) -> int:
    return x + 1

result = my_function.remote(42)  # Returns 43

​
function.local

function.local(*args, **kwargs) -> Any
Call the function locally, without going through Modal’s infrastructure. This runs the function in your local Python interpreter using your local environment. Example: 
@app.function()
def my_function(x: int) -> int:
    return x + 1

result = my_function.local(42)  # Runs locally

​
function.spawn

function.spawn(*args, **kwargs) -> FunctionCall
Spawn a function call and immediately return a FunctionCall handle. The function executes asynchronously, and you can retrieve its result later. Example: 
@app.function()
def my_function(x: int) -> int:
    return x + 1

call = my_function.spawn(42)
# ... do other work ...
result = call.get()  # Get the result when ready

​
function.map

function.map(
    *input_iterators,
    kwargs: dict = {},
    order_outputs: bool = True,
    return_exceptions: bool = False,
) -> Iterator[Any]
Map a function over one or more iterables, executing calls in parallel.
​
input_iterators
Iterable
One or more iterables to map over. If multiple iterables are provided, they are zipped together.
​
kwargs
dict
Keyword arguments to pass to each function call.
​
order_outputs
bool
default:"True"
If True, results are returned in the same order as inputs. If False, results are returned as they complete.
​
return_exceptions
bool
default:"False"
If True, exceptions are returned as values instead of being raised.
​
results
Iterator[Any]
Iterator over the function results.
Example: 
@app.function()
def square(x: int) -> int:
    return x * x

results = list(square.map([1, 2, 3, 4, 5]))
# Returns [1, 4, 9, 16, 25]

​
function.starmap

function.starmap(
    input_iterator,
    kwargs: dict = {},
    order_outputs: bool = True,
    return_exceptions: bool = False,
) -> Iterator[Any]
Like map, but unpacks arguments from the input iterator. Each item in the iterator should be a tuple of arguments. Example: 
@app.function()
def add(x: int, y: int) -> int:
    return x + y

results = list(add.starmap([(1, 2), (3, 4), (5, 6)]))
# Returns [3, 7, 11]

​
function.for_each

function.for_each(
    input_iterator,
    kwargs: dict = {},
    order_outputs: bool = False,
    return_exceptions: bool = False,
) -> Iterator[Any]
Like map, but optimized for side effects rather than return values. Results are returned as they complete (not in order by default).

​
function.update_autoscaler

function.update_autoscaler(
    *,
    min_containers: Optional[int] = None,
    max_containers: Optional[int] = None,
    scaledown_window: Optional[int] = None,
    buffer_containers: Optional[int] = None,
) -> None
Override the current autoscaler behavior for this Function. Unspecified parameters will retain their current value. Subsequent deployments will reset the autoscaler back to its static configuration.
​
min_containers
int
Minimum number of containers to keep running.
​
max_containers
int
Maximum number of containers allowed.
​
scaledown_window
int
Time in seconds before scaling down idle containers.
​
buffer_containers
int
Number of additional idle containers to maintain under active load.
Example: 
f = modal.Function.from_name("my-app", "my-function")

# Always have at least 2 containers running
f.update_autoscaler(min_containers=2, buffer_containers=1)

# Limit to max 5 containers
f.update_autoscaler(max_containers=5)

​
Function.from_name

modal.Function.from_name(
    app_name: str,
    tag: str,
    *,
    environment_name: Optional[str] = None,
    client: Optional[Client] = None,
) -> Function
Reference a Function from a deployed App by its name. This is a lazy method that defers hydrating the local object until it is actually used.
​
app_name
str
required
Name of the deployed App.
​
tag
str
required
Name of the Function within the App.
​
environment_name
str
Environment to look up the Function in.
​
client
Client
Optional Modal client to use.
​
function
Function
The referenced Function instance.
Example: 
f = modal.Function.from_name("my-app", "my-function")
result = f.remote(42)

​
function.with_options

function.with_options(
    *,
    cpu: Optional[Union[float, tuple[float, float]]] = None,
    memory: Optional[Union[int, tuple[int, int]]] = None,
    gpu: GPU_T = None,
    env: Optional[dict[str, Optional[str]]] = None,
    secrets: Optional[Collection[Secret]] = None,
    volumes: dict[Union[str, PurePosixPath], Union[Volume, CloudBucketMount]] = {},
    retries: Optional[Union[int, Retries]] = None,
    max_containers: Optional[int] = None,
    buffer_containers: Optional[int] = None,
    scaledown_window: Optional[int] = None,
    timeout: Optional[int] = None,
    region: Optional[Union[str, Sequence[str]]] = None,
    cloud: Optional[str] = None,
) -> Function
Override the static Function configuration at runtime. This returns a new Function instance that will autoscale independently of the original. Example: 
f = modal.Function.from_name("my-app", "my-function")
f_gpu = f.with_options(gpu="A100")
result = f_gpu.remote(data)  # Runs with A100 GPU
Options can be stacked: 
f.with_options(gpu="A100").with_options(scaledown_window=300)

​
Async methods

All blocking methods have async equivalents with the .aio suffix:
  • function.remote.aio(*args, **kwargs) - Async version of remote()
  • function.spawn.aio(*args, **kwargs) - Async version of spawn()
  • function.map.aio(...) - Async version of map()
  • function.starmap.aio(...) - Async version of starmap()
  • function.for_each.aio(...) - Async version of for_each()
  • function.update_autoscaler.aio(...) - Async version of update_autoscaler()
Example: 
import asyncio

@app.function()
def my_function(x: int) -> int:
    return x + 1

async def main():
    result = await my_function.remote.aio(42)
    print(result)

asyncio.run(main())

Build docs developers (and LLMs) love

Get started for freeTalk to us