modal.Image build chain have a second path: a Docker image with a handler function or an HTTP server.
How Modal maps to Runpod
What’s different
What works differently
Arguments and results are JSON on queue resources. Modal serializes arguments and return values with cloudpickle, so you can pass most Python objects. Runpod queue jobs are JSON. Pass strings, numbers, lists, and dicts, send binary data as base64 or as a URL, and write large outputs to a volume or object storage. Whole-number floats can arrive as integers, so cast numeric inputs. Payload and result limits are smaller. Modal Web Functions accept request bodies up to 4 GiB, and results from.spawn() are kept for 7 days. Runpod queue endpoints accept 10 MB on /run and 20 MB on /runsync, load-balancing endpoints accept 30 MB per request and response, and job results are kept for 30 minutes after an async job and 1 minute after a sync job. If a caller fetches results hours later, send them to a webhook or write them to storage.
Images are assembled differently. A modal.Image is built by chaining methods and cached by Modal. In the Runpod SDK, you list pip packages in dependencies and apt packages in system_dependencies, and rp flash deploy packages your code and dependencies into an artifact of up to 1,500 MB that runs on Runpod’s runtime image. For anything beyond that, set image= to your own image or build a Docker worker.
Classes become functions or route classes. @app.queue wraps a function. To load a model once per worker, cache it in a module-level variable, or move to @app.api, where a method marked @runpod.init runs once when each worker starts. The SDK docs show a startup hook only, so move @modal.exit cleanup into your own shutdown handling.
Web endpoints are authenticated and have a different URL shape. A Modal Web Function gets a modal.run URL and is public by default. A Runpod queue endpoint is called at https://api.runpod.ai/v2/ENDPOINT_ID/runsync with a JSON body under input, and a load-balancing endpoint at https://ENDPOINT_ID.api.runpod.ai/PATH. Both expect Authorization: Bearer with a Runpod API key. If browsers or third parties call your Modal URL without credentials, put a proxy that holds the key in front of the endpoint.
Timeout units change. Modal’s timeout is in seconds and defaults to 300. The SDK’s execution_timeout_ms is in milliseconds and defaults to 0, which means no limit. timeout=600 becomes execution_timeout_ms=600000.
Volumes don’t need commits. A Modal Volume is snapshotted with commit() and refreshed with reload(). A network volume behaves like a mounted file system: writes are visible to other workers right away, so delete the commit() and reload() calls. Queue and API resources mount one volume, always at /runpod-volume. Tasks can mount one network volume and one global volume at paths you choose.
A network volume pins compute to its data center. Every resource that mounts a network volume runs in that volume’s data center, which narrows the GPUs available to it. GPU stock varies by data center, so check live stock before you choose where a volume lives.
Idle endpoints are scaled down. Runpod reduces max workers to 2 on an endpoint that receives no requests for 3 days, and to 0 after 7 days. Raise max workers again before you send traffic to an endpoint that sat unused.
Requests to an empty load-balancing endpoint can fail. Queue endpoints hold jobs until a worker is ready, like Modal Functions. Load-balancing endpoints have no queue, like Modal Servers, so clients should retry while the first worker starts.
Billing is per worker, from a prepaid balance. Modal meters CPU cores, memory, and GPUs as separate line items and invoices monthly. Runpod bills each Serverless worker per second from start to stop, including cold start, execution, and the idle timeout, plus storage, and deducts charges from a balance you fund in advance. Size workers and idle_timeout with that in mind.
What has no direct equivalent
Runpod has features without a Modal counterpart that affect how you design the port:
runpod.Model stages Hugging Face weights on the host before a worker starts, @app.task gives a job a dedicated Pod with no execution limit, and network volumes expose an S3-compatible API so you can load data without running compute.
Requirements
- A Modal workspace you can read with the
modalCLI (modal token infoshows the active token). - A Runpod account with a funded balance.
- Python 3.10 to 3.14 on your machine. Dev sessions and tasks run your code on the same Python version as your local interpreter.
- Docker, only if you use the custom image path.
- The AWS CLI, only if you copy data with the S3-compatible API.
Step 1: Take inventory of what you run on Modal
List every App, in every Environment, with its Functions, Servers, and deployment history:--env ENVIRONMENT_NAME for each Environment. modal app info lists each Function and Server in the App, and modal container list shows what’s running now.
Next, list the storage and configuration objects that Apps reference by name:
modal secret list returns names, not values. Collect the values from the system you created them from, because you’ll re-enter them on Runpod.
Then find the code. This search covers Modal imports, decorators, lookups, CLI calls in scripts and CI, credentials, and hard-coded URLs:
gpu, cpu, memory, ephemeral_disk, timeout, retries, schedule, region, min_containers, max_containers, buffer_containers, scaledown_window, volumes, secrets, the image definition, and any @modal.concurrent or @modal.batched settings. Older code uses names that Modal has since renamed. Treat them as the same settings:
Finally, record who calls each workload: Python callers that use
modal.Function.from_name or modal.Cls.from_name, HTTP clients that call modal.run URLs, which of those URLs require Proxy Tokens, and any custom domains.
Step 2: Set up Runpod
Install the Runpod SDK, which includes therp CLI, and log in:
rp login opens your browser and saves credentials to ~/.runpod/config.toml. In CI, set the RUNPOD_API_KEY environment variable instead. Create keys on the Credentials page.
Install runpodctl to manage endpoints, templates, and volumes from the terminal:
runpodctl doctor configures the API key and checks the setup. On macOS you can also install with brew install runpod/runpodctl/runpodctl. If you automate with an agent, connect the Runpod MCP server.
Step 3: Choose where each workload lands
GPU mapping
Choose the GPU that fits the workload’s memory and throughput needs, then confirm it’s in stock where your data lives. In the SDK, a short name such as"H100" matches every device whose name contains it, and a runpod.GpuGroup pool allows any GPU in that pool. Queue and API resources select hardware by pool. Tasks select by device.
See live stock with
runpodctl gpu list, and see GPU types for every pool and device name. For CPU-only Functions, pick an instance ID from CPU types, for example cpu="cpu3c-2-4" for 2 vCPUs and 4 GB. Modal’s cpu= counts physical cores, and Runpod CPU instances count vCPUs.
Step 4: Move your images and code
Translate the image
Start by deciding whether themodal.Image fits the SDK’s built-in path. This table maps each builder method:
On Runpod’s built-in GPU images,
torch, torchvision, torchaudio, and triton are already installed and are left out of the artifact, so don’t pin them. A custom image= needs Python and pip, because the worker installs the SDK runtime when it starts. All images must be built for linux/amd64, which is the same requirement Modal places on external images.
Two habits carry over unchanged: import heavy packages inside the function body, and keep blocking work out of module scope. Replace modal.is_local() with runpod.is_local().
Construct-by-construct mapping
Example 1: A GPU function called with .remote()
This Modal App embeds text on an L4 and is called from a local entrypoint:embed_modal.py
@app.queue:
embed_runpod.py
rp flash dev embed_runpod.py in place of modal run embed_modal.py. The image definition became dependencies, the timeout changed from seconds to milliseconds, and max_containers=5 became the upper bound of workers. The function already returns a list, so its result is valid JSON.
Example 2: A class that loads a model in @modal.enter
This Modal Cls loads a text-generation model once per container, caches weights on a Volume, and keeps one container warm:textgen_modal.py
.remote() or .spawn(), and an API resource when you want HTTP routes.
- Queue resource
- API resource
The queue version caches the pipeline in a module-level variable, so the load runs once per worker:
textgen_runpod.py
Generator().generate.remote(...) became generate.remote(...). The Volume used as a Hugging Face cache became runpod.Model, which stages the weights on the host before the worker starts, and qwen.path points to them inside the worker.min_containers=1 became workers=(1, 4), which keeps one worker running and billed at all times. The Modal Secret named huggingface held an HF_TOKEN key. On Runpod, the secret hf-token holds the token value and the env mapping names the variable. If your weights aren’t on Hugging Face, mount a network volume at /runpod-volume and see Volume cache for loading them quickly.
Example 3: A FastAPI web endpoint
This Modal ASGI app serves two routes, handles 20 concurrent requests per container, and requires a Proxy Token:classify_modal.py
- API resource
- Load-balancing endpoint with your FastAPI app
When the routes take and return JSON, translate them to an A GET route takes no arguments and a POST route takes the JSON body. FastAPI features such as path parameters, Pydantic request models, middleware, and streaming responses aren’t part of this route model, so use the custom image tab if you depend on them.
@app.api class:classify_runpod.py
Authorization: Bearer with a Runpod API key in place of the Modal-Key and Modal-Secret headers. @modal.concurrent has no argument on API resources: the routes are async, and the endpoint scales on request count (scaler_type="REQUEST_COUNT", scaler_value=4 by default).
Example 4: A training job with a Volume and Secrets
This Modal Function trains on an H100, checkpoints to a Volume, logs to Weights & Biases, and retries after a failure:train_modal.py
train_runpod.py
rp flash dev train_runpod.py --once, which runs the entrypoint a single time and exits with an error if it fails. The changes from the Modal version:
ckpt.pathreturns the mount path inside the task. Read it inside the function, not at module level.ckpt.commit()is gone. Writes to a network volume are durable as they happen.torchisn’t independencies, because the built-in GPU image provides it.- There’s no
timeout. Tasks have no execution limit, so a hung job keeps billing until you stop it. To bound a run, calljob = train.spawn(...)and thenawait job.wait(timeout=...), which terminates the Pod when the wait ends. - There’s no
retries. The resume logic stays, and you run the task again after a failure.
The custom image path: a handler function
When an App can’t fit the SDK’s dependency model, build a Docker image with a handler function. The handler receives each job as a dict and returns a JSON-serializable result. This handler does the same job as the Modal Cls in Example 2:handler.py
modal.Image chain line for line:
Dockerfile
python handler.py --test_input '{"input": {"prompt": "Runpod is"}}' before you build. A generator handler streams results the way remote_gen does, and a concurrency_modifier replaces @modal.concurrent. See Concurrent handlers. You can also let Runpod build the image from a repository with the GitHub integration.
Step 5: Move your data and models
Secrets
Re-create each key of each Modal Secret as a Runpod secret:rp secret add prompts for the value, which keeps it out of your shell history. Secret names must be unique in the account, start with a letter or underscore, and can’t start with runpod. In SDK code, reference a secret with env={"HF_TOKEN": runpod.Secret("hf-token")}. In a template or endpoint you create outside the SDK, set the environment variable’s value to {{ RUNPOD_SECRET_hf-token }}. A changed secret takes effect the next time a worker or Pod boots. See Manage secrets.
Hugging Face models
If a Volume only caches Hugging Face downloads, don’t copy it. Usemodel=runpod.Model("owner/name") on a queue or API resource, or --model-reference on an endpoint you create with runpodctl. Runpod stages the weights on the host before the worker starts. Gated models need HF_TOKEN on the same resource. See Cached models.
Volumes
Create a network volume in the data center where you plan to run. Check GPU stock there first, because every resource that mounts the volume runs in that data center:runpod.NetworkVolume("checkpoints", create=False) then refers to this volume by name.
Download the Modal Volume and upload it to the network volume through the volume’s S3-compatible API. You need an S3 API key from the Credentials page and a data center that supports the API. Configure the AWS CLI with that key (aws configure), then sync:
/runpod-volume on Serverless workers and /workspace on Pods. aws s3 sync can have trouble with more than 10,000 files or deeply nested trees, so for large trees copy from inside a Pod as shown next. See S3-compatible API for the supported data centers and endpoint URLs.
For a Volume too large to stage on your machine, copy from inside Runpod. Start a CPU Pod with the network volume attached, then run the Modal CLI there:
Cloud bucket mounts
modal.CloudBucketMount presents an S3, R2, or GCS bucket as a directory. On Runpod, choose one of these:
- Read and write the bucket from your code with
boto3or the provider’s SDK, with credentials in Runpod secrets. This suits buckets that stay the source of truth. - Copy the data to a network volume once, with
aws s3 syncorrclonefrom a Pod, when workers need file system access to a fixed dataset. - Use Cloud Sync to move data between a Pod and S3, Google Cloud Storage, Azure Blob Storage, Backblaze B2, or Dropbox.
Dicts and Queues
Export any state you need frommodal.Dict objects before you shut down (modal dict items DICT_NAME --all --json), and load it into the store that replaces them. Values are pickled Python objects, so convert them to a portable format as you export.
Step 6: Deploy on Runpod
SDK apps
Deploy from the project directory:rp flash deploy finds every app in the directory, builds an artifact, and creates or updates the endpoints for queue and API resources. It prints a link to each endpoint when it finishes. --env plays the role of modal deploy --env, and running the command again updates the deployment in place. Tasks aren’t deployed as endpoints. They provision a Pod each time your code calls them.
Before you deploy to production, pin GPUs instead of using GpuGroup.ANY, set execution_timeout_ms, and set workers explicitly. See Configuration best practices.
Deploys and dev sessions add your account API key as
RUNPOD_API_KEY to each endpoint’s environment so that one resource can call another. Anyone who can read the endpoint’s template can read that key, so limit who has access to the account or team.Queue endpoint from a custom image
Build and push the handler image forlinux/amd64, then create a Serverless template and an endpoint:
--gpu-id accepts a pool ID or a device ID, and --execution-timeout is in seconds here. --model-reference attaches a cached model under /runpod-volume/huggingface-cache/hub/. A custom handler doesn’t look there on its own, so the template sets HF_HUB_CACHE to that path. Without it, the handler downloads the weights again on every cold start. Add --network-volume-id VOLUME_ID to mount a network volume at /runpod-volume. For a private registry, save credentials with runpodctl registry create and pass --registry-auth-id when you create the template. In the console, the same flow is Serverless, then New Endpoint, then Import from Docker Registry.
Load-balancing endpoint from a custom image
The endpoint type is set at creation through REST API v2 or the console.runpodctl serverless create creates queue-based endpoints. Create a load-balancing endpoint with a POST to /v2/serverless:
type and scaling are required, and load-balancing endpoints scale on REQUEST_COUNT. Set PORT_HEALTH whenever you change PORT, because each defaults to 80 on its own. The response includes the endpoint ID and its request URLs. REST v2 defaults differ from the console’s: flashboot defaults to OFF and workers.idleTimeout to 10 seconds, so set them. In the console, choose Load Balancer under Endpoint Type. See Build a load balancing worker.
Step 7: Update the code that calls Modal
Python callers
Code that looks up a deployed Modal Function changes to a Runpod client. Before:caller_modal.py
caller_runpod.py
runpod.Queue and runpod.Api target the default environment unless you pass env=. They authenticate with rp login credentials or RUNPOD_API_KEY, in place of MODAL_TOKEN_ID and MODAL_TOKEN_SECRET.
For any queue endpoint, including one built from a custom image, call it by ID:
caller_endpoint.py
{"input": {...}}. For a function deployed with @app.queue, the keys of input are the function’s keyword arguments.
HTTP callers
A request to a Modal Web Function looks like this:input and the result comes back under output:
id, status, delayTime, executionTime, and output, so update clients that read the bare return value.
Long requests, polling, streaming, and webhooks
Job states are
IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, and TIMED_OUT. A job that isn’t picked up or finished within its TTL (24 hours by default) is removed, so set policy.ttl and policy.executionTimeout on long jobs. See Send API requests for rate limits and retry guidance.
Automation and CI
Replace Modal CLI calls in CI with their Runpod counterparts from the CLI command map, and replace theMODAL_TOKEN_ID and MODAL_TOKEN_SECRET secrets with RUNPOD_API_KEY. Use rp flash dev main.py --once as the smoke test that modal run provided. For infrastructure you manage outside the SDK, use REST API v2 or the Terraform provider, which is built on REST API v2.
Step 8: Verify, cut over, and shut down
-
Send a real request from outside. Call the deployed endpoint from the network your clients use, with a production-shaped payload, and check the health of a queue endpoint:
- Compare outputs and latency. Run the same inputs through Modal and Runpod. Compare results, then measure a cold request (no workers running) and a warm request separately. The endpoint’s Metrics tab shows delay time, execution time, and cold start time.
-
Run both in parallel. Keep the Modal App deployed. Send a small share of traffic to Runpod from your client or gateway, and watch error rates,
429responses, and queue delay. -
Shift traffic. Raise
workersto cover peak load before you move the rest. Check that the maximum fits your account’s worker limit. -
Set cost guards on Runpod. Set
execution_timeout_mson every queue and API resource, keepworkersmaximums deliberate, and remember that a minimum above 0 bills continuously. Review spend on the Billing page. -
Stop billing on Modal. After the parallel run, stop each App, then delete storage and Secrets you’ve already copied:
modal app stopis permanent, so scheduled Functions in the App stop running too. Deleting a Volume deletes its data, so verify the copy on Runpod first. Checkmodal endpoint stop --helpfor its arguments, and repeat for each Environment with--env. Then rotate or delete the Modal tokens and Proxy Tokens your callers used.
Reference
CLI command map
SDK call map
Configuration field map
Environment variable map
Migrate with a coding agent
A coding agent with the Runpod skills and MCP server can do the inventory, translate the code, and deploy with your approval. Install both first.- Claude Code
- Other agents
The plugin also connects the hosted MCP server:
Troubleshooting
arguments must be json-serializable, or a JSON TypeError when calling a function. The function takes or returns a Python object that Modal pickled, such as a NumPy array, a DataFrame, or bytes. Convert to lists, base64 strings, or a URL to a file on a volume or in object storage.
A job is killed almost immediately. A Modal timeout in seconds was copied into execution_timeout_ms. Multiply by 1,000.
gpu and cpu are mutually exclusive. A Modal Function that set both gpu= and cpu= or memory= was translated argument by argument. Remove cpu from GPU resources.
ImportError when you start a dev session or deploy. The SDK imports your module locally to discover resources, so a top-level import torch needs torch on your machine. Move the import into the function body. If you used with image.imports(): on Modal, move those imports too.
A sibling module imports under rp flash deploy but not under rp flash dev. Dev sessions send only the app’s file. Inline the helper or install it as a package.
Reading volume.path raises an error, or files are missing. The path was read at module level, where the volume isn’t mounted, or a queue or API resource mounted the volume somewhere other than /runpod-volume. Read .path inside the function and change paths that pointed at the old Modal mount point.
Workers don’t start, or the endpoint is throttled. The network volume pins the endpoint to one data center, and the GPU you chose is scarce there. Allow more GPU types with a list, or move the volume to a data center with stock for the GPU you need.
rp flash deploy fails on a resource name, but the dev session worked. Queue and API names need at least 3 characters, and dev sessions don’t check. Rename the function or class, or pass name=.
The build artifact is larger than 1,500 MB. Leave out packages the worker image already has with --exclude, add data files to .runpodignore, or move to a custom image.
Callers get 401. Clients that called a public modal.run URL send no credentials. Add Authorization: Bearer with a Runpod API key. If the SDK returns 401 while rp login succeeded, a stale RUNPOD_API_KEY in your shell is taking precedence. Unset it.
A load-balancing endpoint returns no workers available or 502. The first worker is still starting, or the server isn’t listening where the load balancer checks. Retry with backoff during cold starts, serve /ping, and set PORT and PORT_HEALTH to the port your server uses.
/status/JOB_ID returns 404 for a job that finished. Results are kept for 30 minutes after an async job. Fetch sooner, use a webhook, or write results to storage.
An endpoint that worked last week queues jobs without starting workers. It received no requests for several days, so Runpod lowered its max workers. Raise max workers in the console or with runpodctl serverless update ENDPOINT_ID --workers-max 3.
.remote() on a queue function raises TimeoutError on a long job. Depending on your SDK version, a blocking call on a queue resource can stop waiting after a few minutes while the job keeps running. Use job = fn.spawn(...) and job.result(timeout=...) for long jobs, or move the work to @app.task.
If you find a gap or an error in this guide, open an issue in the Runpod docs repository.
Next steps
Runpod SDK overview
Apps, queue resources, tasks, API resources, and call styles.
Resource parameters
Every argument on
@app.queue, @app.api, and @app.task.Load-balancing endpoints
Serve your own HTTP server with custom paths.
Network volumes
Persistent storage for models, datasets, and checkpoints.