gslocal runs your Gradescope autograder locally in Docker against any submission. No uploads, and no waiting on Gradescope.
The difference from hitting the "Run Tests" button is that gslocal mirrors Gradescope's exact container workflow: it builds your autograder zip, spins up the same Docker base image Gradescope uses, mounts the submission, runs the grader, and prints a formatted score summary. That catches the bugs your IDE can't, like missing dependencies, setup.sh mistakes, path assumptions, and anything else that only surfaces inside Gradescope's container. Build and image caching mean repeat runs are fast.
- Python 3.9+
- Docker Desktop (running)
- Git
pip install gslocalIn your autograder project directory, run:
gslocal initThis walks you through creating a gslocal.toml config file. Run gslocal init --placeholders intead to write a config with sentinel values and no prompts, then edit it yourself.
Then test a submission:
gslocal run path/to/submission.zipgslocal expects your autograder project to produce a Gradescope-compatible zip file via a build command. It is agnostic about your build tool - Maven, Make, a shell script, anything that outputs a zip works.
On each run, gslocal:
- Prepares the submission (zip, directory, or GitHub clone)
- Runs your build command if source files changed since the last build
- Generates a Dockerfile and builds a Docker image if the zip is fresh
- Runs the container with the submission mounted, waits for results
- Prints a formatted score summary
Build caching: gslocal hashes the files listed in your watch config. If nothing changed and the output zip exists, the build is skipped entirely. The Docker image is similarly only rebuilt when the zip changes.
gslocal is configured via a gslocal.toml file in your autograder project root. Run gslocal init to generate one interactively.
[build]
cmd = "mvn clean package" # command to produce the autograder zip
zip = "target/*.zip" # glob pattern locating the output zip
watch = ["src/**/*", "pom.xml"] # glob patterns to watch for rebuild triggering
[docker]
setup = "src/main/resources/setup.sh" # path to setup.sh inside the project (required)
# metadata = "src/main/resources/mock_submission_metadata.json" # optional
[run]
timeout = 60 # autograder timeout in seconds
verbose = false # show full build/docker output instead of spinnersField reference:
| Field | Required | Description |
|---|---|---|
build.cmd |
yes | Shell command to build the autograder zip |
build.zip |
yes | Glob pattern to locate the output zip |
build.watch |
yes | Glob patterns whose content is hashed to detect source changes |
docker.setup |
yes | Path to setup.sh relative to project root |
docker.metadata |
no | Path to mock submission metadata JSON; a bundled default is used if omitted |
run.timeout |
no | Container timeout in seconds (default: 60) |
run.verbose |
no | Show full build and Docker output (default: false) |
gslocal locates gslocal.toml by walking up the directory tree from your current working directory, so you can run it from any subdirectory of your project.
gslocal accepts submissions in three formats:
# Zip file
gslocal run test-zips/solution.zip
# Local directory
gslocal run /path/to/student/project/
# GitHub URL (SSH or HTTPS)
gslocal run git@github.com:student/repo.git
gslocal run https://github.com/student/repoGitHub submissions are cloned with --depth 1.
Run the autograder against a submission.
| Flag | Description |
|---|---|
-r, --rebuild |
Force rebuild of build command and Docker image |
-n, --no-build |
Skip build, use existing zip |
-i, --interactive |
Drop into a shell inside the container |
-c, --clean |
Delete temp files after the run |
-t, --timeout SECS |
Override timeout (also: GSLOCAL_TIMEOUT env var) |
-v, --verbose |
Show full build and Docker output |
Timeout precedence: --timeout flag > GSLOCAL_TIMEOUT env var > gslocal.toml value > 60s default.
After each run, the following are available for inspection:
.gslocal/
temp/
submission/ # prepared submission files
results/ # results.json
autograder/ # extracted autograder zip contents
Generate a gslocal.toml in the current directory. Prompts for each field with example hints. Skipping a required field writes a placeholder value that gslocal will catch and refuse to run with.
| Flag | Description |
|---|---|
--placeholders |
Write config with all sentinel values, no prompts |
Remove local gslocal state for the current project.
| Flag | Description |
|---|---|
| (none) | Delete .gslocal/temp/ only |
--image |
Also remove the Docker image for this project |
--all |
Delete .gslocal/ entirely and remove Docker image (full reset) |
gslocal stores all state in a .gslocal/ directory at the project root. Add it to your .gitignore (gslocal init offers to do this automatically):
.gslocal/
- Install gslocal:
pip install gslocal - Run
gslocal initin your autograder project root - Fill in your build command, zip output path, and the files to watch for changes
- Add
.gslocal/to.gitignore - Run
gslocal run <submission>to test
Contributions are welcome. See CONTRIBUTING.md for setup instructions, project layout, and pull request guidelines.
gslocal is released through the GitHub Actions workflow at .github/workflows/publish.yml.
Before cutting a release:
- Update
versioninpyproject.toml - Add a matching section to
CHANGELOG.md, for example## [0.1.1] - 2026-05-02 - Merge the release-ready changes to
main
Then, in GitHub:
- Open
Actions - Select
Release and Publish - Click
Run workflow - Enter the version number, such as
0.1.1
The workflow will:
- verify the run is on
main - verify the requested version matches
pyproject.toml - verify
CHANGELOG.mdcontains a section for that version - fail if that version is already published on PyPI
- build the package and run
twine check - create the
v<version>tag if needed - create the GitHub Release from the matching changelog section if needed
- publish the package to PyPI
If the GitHub tag or release is created but PyPI publishing fails, fix the issue and rerun the workflow for the same version. If PyPI already has that version, publish a new patch version instead.