Skip to main content
This guide is for teams that run production workloads on Modal and want to run them on Runpod. Modal Functions and Clses map to queue resources in the Runpod SDK, Web Functions and Servers map to API resources and load-balancing endpoints, long jobs map to tasks, Volumes map to network volumes, and Secrets map to Runpod secrets. When you finish, each workload runs on Runpod, your callers use Runpod URLs or the Runpod client, and your Modal Apps are stopped. Most of the work is a code translation, because both platforms define infrastructure with Python decorators. Apps that depend on a long modal.Image build chain have a second path: a Docker image with a handler function or an HTTP server.
You can hand this migration to a coding agent. See Migrate with a coding agent.

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 modal CLI (modal token info shows 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:
Repeat the App commands with --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:
For each Function, Cls, and Server, record these settings from its decorator: 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 the rp 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 the modal.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().
In a dev session (rp flash dev), only the file that defines the app is sent to workers. A project that imports sibling modules works with rp flash deploy, which packages the project directory, but fails in a dev session. Keep helpers in the app file or in an installable package while you iterate.

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
The Runpod version keeps the function body and moves the configuration onto @app.queue:
embed_runpod.py
Run it with 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
On Runpod you have two shapes. Use a queue resource when callers used .remote() or .spawn(), and an API resource when you want HTTP routes.
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
When the routes take and return JSON, translate them to an @app.api class:
classify_runpod.py
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.
On both paths, callers send 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
On Runpod this is a task. Each call gets its own Pod, and the Pod is terminated when the function returns:
train_runpod.py
Run it with 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.path returns 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.
  • torch isn’t in dependencies, 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, call job = train.spawn(...) and then await 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.
A task started with .spawn() that you never wait on or cancel keeps its Pod running after your script exits. Check the Pods page after interrupted runs.

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
The Dockerfile replaces the modal.Image chain line for line:
Dockerfile
Test the handler locally with 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. Use model=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:
The command returns the volume ID. Size is in GB, from 10 to 4096, and you can grow a volume later but not shrink it. In SDK code, 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:
Files land at the volume root, which is /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:
Use a short-lived Modal token for this and rotate it afterward, because environment variables are visible in the Pod’s configuration. To serve the same files in several data centers, either create one network volume per data center and copy the data to each, or use a global volume. Global volumes are in beta, attach to GPU compute, are billed for storage and requests, and don’t support file locking or atomic rename. The S3-compatible API works with network volumes only, so load a global volume from a Pod.

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 boto3 or 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 sync or rclone from 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 from modal.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 for linux/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
After, using resources deployed with the Runpod SDK:
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
The client wraps your dict as {"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:
For an API resource or a load-balancing endpoint, change the host and the auth header. The path and body stay the same:
For a queue endpoint, the body moves under input and the result comes back under output:
The response is a JSON envelope with 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 the MODAL_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

  1. 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:
  2. 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.
  3. 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, 429 responses, and queue delay.
  4. Shift traffic. Raise workers to cover peak load before you move the rest. Check that the maximum fits your account’s worker limit.
  5. Set cost guards on Runpod. Set execution_timeout_ms on every queue and API resource, keep workers maximums deliberate, and remember that a minimum above 0 bills continuously. Review spend on the Billing page.
  6. Stop billing on Modal. After the parallel run, stop each App, then delete storage and Secrets you’ve already copied:
    modal app stop is permanent, so scheduled Functions in the App stop running too. Deleting a Volume deletes its data, so verify the copy on Runpod first. Check modal endpoint stop --help for its arguments, and repeat for each Environment with --env. Then rotate or delete the Modal tokens and Proxy Tokens your callers used.
Undeploying a Runpod app doesn’t delete the network volumes it created, and they keep billing. If you roll back to Modal, delete volumes you no longer need from the Storage page or with runpodctl network-volume delete.

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.
The plugin also connects the hosted MCP server:
The MCP server signs in with OAuth (Sign in with Runpod), so you don’t need an API key to start. See Agent skills and MCP servers for agent and client IDs. Then give the agent this prompt from the root of your repository:

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.
Last modified on November 14, 2026