mcc

Compile and run CUDA C/C++ programs on a Modal GPU. Requires Python 3.12+ and a Modal account with GPU access.

uv tool install modal-cuda
uvx modal token new
mcc sample.cu --gpu T4

For a one-off run: uvx --from modal-cuda mcc sample.cu.

Usage

mcc input.cu [options] [-- program arguments]

mcc sample.cu --gpu A100 --nvcc-arg=-O3 -- --size 4096

Everything after -- is passed unchanged to the executable. Commands run without a shell. Standard input is closed; interactive programs are not supported.

Choose an image and --nvcc-arg architecture flags compatible with your GPU. The CLI does not select a toolkit or architecture automatically.

Projects and results

mcc src/main.cu --project . --source src/helper.cu \
  --nvcc-arg=-Iinclude --nvcc-arg=-O3 \
  --download results/output.bin --output-dir runs/first \
  -- --input data/input.bin

Local source paths are relative to your shell's working directory. All sources must be inside --project. The project keeps its directory layout, so headers and data files are available remotely. Without --project, only the input file is uploaded and the executable runs beside that file.

Uploads respect the project root's .gitignore, then .mccignore, using Git-style patterns. Nested ignore files are not read. .git, .venv, Python/test/lint caches, symlinks, and the selected output directory are skipped. An explicitly selected source excluded by these rules is an error. Add private files and large unused data to .mccignore before uploading a project.

Downloads accept regular files only, with no globs, directories, symlinks, absolute paths, or ... Parent directories are created locally. Existing destination files are never overwritten. Transfers are staged; incomplete transfers are discarded. Completed files are published individually once the remote stream finishes. Files can still be downloaded after a nonzero program exit, which preserves that exit code. Compile failures, timeouts, and cancellation skip downloads.

Output and failures

Compiler and program output stream as bytes arrive, preserving stdout and stderr. CLI status messages go to stderr, so redirection works:

mcc sample.cu >stdout.txt 2>stderr.txt

The program controls its own buffering. Call fflush(stdout) after progress messages in C/C++ when you need them immediately. Output order is preserved within each stream; ordering between stdout and stderr is not guaranteed.

Compiler and program exit codes are returned to your shell. Signals use 128 + signal; timeout returns 124, Ctrl-C 130, invalid CLI arguments 2, and other CLI/transfer failures 1. The remote app is stopped when the command ends.

Development

uv sync
uv run python -m mcc sample.cu
uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv build

The default tests use local files and real subprocesses, with no mocks. Run the GPU tests separately; they make real Modal calls on a T4 and incur GPU usage:

MCC_TEST_MODAL=1 uv run pytest -q tests/test_modal.py

These cover a CUDA kernel, multiple source files, ignored files, arguments, binary downloads, live output, compiler/program failures, timeout, and cancellation.

License

MIT © ExpressGradient