modal-examples: a runnable tour of Modal's serverless Python model, and what it does not cover

The problem is Modal's programming model, not Python packaging

Modal is a platform for running Python functions in cloud containers that are created on demand. The hard part of adopting something like that is not installing a package. It is understanding how a local script maps onto remote execution: which code runs on your laptop, which code runs in the container, how files and data get there, and what a function has to declare before it can be scheduled. modal-examples exists to answer those questions with runnable files rather than prose. The README describes the collection as a way to "learn Modal and build your own robust and scalable applications", and the folder structure does the teaching: 01_getting_started through 14_clusters form a guided sequence, with a misc/ folder for examples that do not fit the categories. The audience is therefore narrow and specific. It is a Python developer who already knows how to write functions and wants to know what changes when those functions are dispatched to someone else's infrastructure. It is not aimed at someone choosing between cloud providers, and it contains nothing that would help with that decision.

What actually happens when you type modal run

The README is explicit about the execution split: the scripts are run on your local machine, but they communicate with Modal and run in Modal's cloud, spawning serverless containers on demand. That single sentence describes the whole architecture of every example in the repository. Your local process is the client. It reads the file, sends the relevant definitions to Modal, and the container image described in the file is built or reused remotely. The function then executes there. This is why the examples can be read as ordinary Python: the decorators and image definitions are declarations about the remote side, not code that runs locally. The consequence for a reader is that an example file is not self-contained in the way a normal script is. Copying a function into your own project without the accompanying image definition or mount will not reproduce the behaviour you saw. The 14 numbered folders exist because that mapping has enough surface area to deserve a sequence: the later folders cover clusters, which implies coordination across more than one container, while the early ones cover the basic run loop.

Running an example requires an account before it requires the repository

The documented path is short and has a hard prerequisite. You sign up at modal.com, follow the setup instructions to install the modal package, and set your API key. Only then does the repository do anything. The README gives one command as the canonical form: modal run 01_getting_started/hello_world.py, and notes that files in any folder can generally be run much like ordinary Python programs with a command of that shape. Two details are worth pulling out. First, the word "generally" is doing real work: the README does not promise that every file in every folder runs identically, and there is no per-example documentation in the material provided. Second, the API key is the actual configuration key here. There is no config file format, no environment variable list, and no dependency manifest described in the README. If you need to know what a specific example requires beyond the modal package, the README does not tell you, and you would have to read the example file itself.

The 3.11 testing claim is narrower than it sounds

The README states that the examples are continuously tested for correctness against Python 3.11. That is a meaningful signal about the repository's own health, and it is also a boundary. It says nothing about 3.12 or 3.13, and it says nothing about the Modal client version the tests run against. This matters because the repository has no retrieved releases. There is no version tag to pin, no changelog to read, and no compatibility matrix. If you adopt an example today and return to it in six months, the only version marker you have is the commit you copied. The practical failure mode is quiet: a pattern that worked in an example stops matching the current Modal API, and because the example is a script rather than an installed dependency, nothing warns you. The testing claim also does not extend to the examples' third-party dependencies. A folder that demonstrates GPU work will reference libraries whose versions are whatever the example file specifies, and the README does not describe a lockfile or a constraints file anywhere.

Where the repository stops being the right tool

Three cases where modal-examples is the wrong choice. First, if you want a starting point for a real service, the repository gives you isolated scripts, not an application layout. There is no described structure for tests, configuration, secrets management, or deployment, because the examples are meant to be read one at a time. Second, if you need performance or cost numbers, the material contains none, and the repository is not positioned as a benchmark set. Any figure you see in an example is illustrative of an API call, not a measurement you can rely on. Third, if you are evaluating Modal against a self-managed alternative, the examples cannot help you make that comparison, because they only demonstrate the Modal path. They show what the code looks like when the platform is assumed. They do not show what the same workload costs to operate, how it behaves under contention, or what happens when a container fails mid-run. Those are the questions that decide an adoption, and they are outside the scope of a teaching repository.

Ray and Kubernetes solve the same problem from the opposite direction

The closest alternatives are not other example repositories. They are the systems you would otherwise use to run Python functions on remote hardware. Ray asks you to define tasks and actors and then manage or connect to a cluster yourself, whether that cluster is on your own machines or rented. Kubernetes asks you to describe workloads as container specifications and leaves scheduling, scaling, and image building to a control plane you operate. Modal inverts the default: the README's framing is that you write Python and the platform handles the container lifecycle, with the local script acting as the client. The difference shows up in what you own. With Ray or Kubernetes, the cluster is yours to size, patch, and pay for whether or not work is running. With the model these examples demonstrate, the container appears when a function is called. That trade is the whole argument, and it is a trade rather than a win: you give up control over the runtime environment and the scheduling policy in exchange for not operating them. The examples let you see the developer-facing half of that trade. They cannot show you the operational half.

Licence, maintenance, and what the MIT grant does not settle

The repository is MIT licensed, which permits reuse, modification, and redistribution with the licence text preserved, and it comes with no warranty. For an examples repository that is the permissive outcome you would expect, and it means copying a file into your own project is straightforward from a licensing standpoint. It does not mean the examples are maintained as a dependency. There are no releases, so there is no upgrade path in the usual sense: the only way to take an update is to track the main branch, and the only way to stay stable is to pin a commit. The maintenance cost therefore falls on you in a specific way. You are not paying to keep a library current. You are paying to notice when a pattern you copied no longer matches the platform, and the README gives you no mechanism to notice. The continuous testing against Python 3.11 protects the repository's own correctness. It does not protect your copy of it. This is not legal advice, and the licence text in the LICENSE file is the authority on what the grant covers.

Editorial conclusion

Adopt modal-examples if you are evaluating Modal and want to see its programming model in working Python before committing to a rewrite, or if you are teaching a team the modal run workflow. Do not adopt it if you need a production scaffold, pinned dependencies, or evidence about throughput and cost: the repository is a teaching set, not an application. Before building on any example, check two things yourself: whether the file you are copying still matches the current Modal API, since there are no tagged releases to pin against, and whether its dependencies are declared in a way you can reproduce outside the example folder.

Official sources

1. Issues
2. License: MIT
3. modal-labs/modal-examples on GitHub
4. Project website
5. README