Skip to main content
The fal runtime is the recommended way to define your app’s environment. Instead of writing a Dockerfile, you list your pip dependencies in the requirements attribute and fal builds an optimized, cached environment for you. This approach handles CUDA setup, PyTorch index URLs, and environment isolation automatically based on your chosen machine type. If you need system-level packages, a specific base image, or a non-Python runtime, use a custom container instead. If you need to include local Python modules or clone external repositories, see Import Code. For an overview of when to use which approach, see Environment and Runtime.

​
Defining Requirements

The requirements attribute in your fal.App class is where you specify the Python packages your model needs. fal ensures these are installed in the runner’s environment before setup() is called. 
import fal

class MyModel(fal.App):
    machine_type = "GPU-A100"
    
    requirements = [
        "torch==2.4.0",
        "transformers",
        "diffusers",
        "accelerate"
    ]
    
    def setup(self):
        import torch
        ...
Pin your package versions (e.g., torch==2.4.0) to ensure reproducible builds. Use the requirements attribute instead of running pip install inside setup(), since packages in requirements are installed during the container build and cached across deploys. Only include the packages your app actually needs to keep startup times short. When you deploy, fal creates an isolated environment based on your machine_type, installs your listed packages, and caches the resulting container image. On subsequent deploys, unchanged requirements are served from cache. Your setup() method then runs on the provisioned runner to load the model into memory.

​
Using Prebuilt Wheels

You can install packages directly from wheel URLs. This is useful for custom-built packages or packages not available on PyPI.

​
Direct URL

Provide the full URL to a wheel file: 
requirements = [
    "https://your-storage.example.com/wheels/mypackage-1.0.0-cp311-cp311-linux_x86_64.whl",
]

​
Package @ URL (PEP 440)

Use the package@url syntax to give the package a name for dependency resolution: 
requirements = [
    "mypackage@https://your-storage.example.com/wheels/mypackage-1.0.0-cp311-cp311-linux_x86_64.whl",
]
This syntax is recommended when other packages depend on mypackage, as pip can properly track the dependency.

​
Alternative Package Indexes

Use --extra-index-url or --find-links to install packages from alternative sources.

​
Extra Index URL

Install packages from an additional PyPI-compatible index: 
requirements = [
    "torch==2.5.0",
    "--extra-index-url",
    "https://download.pytorch.org/whl/cu124",
]
The --extra-index-url flag must appear before any packages that need it. Place index flags at the beginning or directly before the relevant packages.
Use --find-links to search for packages in a directory or URL containing wheel files: 
requirements = [
    "mypackage",
    "--find-links",
    "https://github.com/your-org/releases/download/v1.0.0/",
]

​
Multiple Indexes

Combine multiple index sources when needed: 
requirements = [
    "--extra-index-url",
    "https://download.pytorch.org/whl/cu124",
    "--extra-index-url",
    "https://your-company.example.com/simple",
    "torch==2.5.0",
    "your-internal-package==1.0.0",
]

​
Private Packages

​
Private Git Repositories

Install directly from a private GitHub repository using a personal access token: 
requirements = [
    "git+https://YOUR_TOKEN@github.com/your-org/private-repo.git",
]
Pin to a specific commit or tag for reproducibility: 
requirements = [
    "git+https://YOUR_TOKEN@github.com/your-org/private-repo.git@v1.0.0",
    "git+https://YOUR_TOKEN@github.com/your-org/private-repo.git@abc123def",
]
Security Consideration: Tokens embedded in requirements are visible in your code. For better security:
  • Use short-lived tokens when possible
  • Consider hosting wheels on a storage service with pre-signed URLs
  • Use fal secrets for sensitive values in your app code

​
Private PyPI Index

Install from a private PyPI server with authentication: 
requirements = [
    "--extra-index-url",
    "https://username:password@pypi.your-company.com/simple",
    "your-private-package==1.0.0",
]

​
Pre-signed URLs

For private storage (S3, GCS, etc.), generate a pre-signed URL with an expiration time: 
requirements = [
    "https://your-bucket.s3.amazonaws.com/wheels/mypackage-1.0.0.whl?AWSAccessKeyId=...&Signature=...&Expires=...",
]

​
Dynamic Wheel Selection

When you need different wheels for different Python versions or platforms, use a helper function: 
def get_package_wheel():
    import sys
    wheels = {
        10: "https://example.com/wheels/mypackage-1.0.0-cp310-cp310-linux_x86_64.whl",
        11: "https://example.com/wheels/mypackage-1.0.0-cp311-cp311-linux_x86_64.whl",
    }
    return wheels[sys.version_info.minor]


class MyApp(fal.App):
    machine_type = "GPU-A100"
    requirements = [
        "torch==2.5.0",
        get_package_wheel(),
    ]
Helper functions are evaluated at deploy time on your local machine, so they have access to local environment variables and can make decisions based on the target Python version.

Importing Local Code

Learn how to bring your local Python modules and files into the fal runtime.