gslocal

Run your Gradescope autograder locally against any submission, without uploading anything to Gradescope.

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. Build and image caching mean repeat runs are fast.

Requirements

• Python 3.9+
• Docker Desktop (running)
• Git

Installation

pip install gslocal

Quick Start

In your autograder project directory, run:

gslocal init

This walks you through creating a gslocal.toml config file. Then test a submission:

gslocal run path/to/submission.zip

How It Works

gslocal 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:

1. Prepares the submission (zip, directory, or GitHub clone)
2. Runs your build command if source files changed since the last build
3. Generates a Dockerfile and builds a Docker image if the zip is fresh
4. Runs the container with the submission mounted, waits for results
5. 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.

Configuration

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 spinners

Field reference:

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.

Submission Types

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/repo

GitHub submissions are cloned with --depth 1.

Commands

gslocal run <submission>

Run the autograder against a submission.

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

gslocal init

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.

gslocal clean

Remove local gslocal state for the current project.

Project State

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/

Adding gslocal to an Existing Autograder

1. Install gslocal: pip install gslocal
2. Run gslocal init in your autograder project root
3. Fill in your build command, zip output path, and the files to watch for changes
4. Add .gslocal/ to .gitignore
5. Run gslocal run <submission> to test

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup instructions, project layout, and pull request guidelines.

Releasing

gslocal is released through the GitHub Actions workflow at .github/workflows/publish.yml.

Before cutting a release:

1. Update version in pyproject.toml
2. Add a matching section to CHANGELOG.md, for example ## [0.1.1] - 2026-05-02
3. Merge the release-ready changes to main

Then, in GitHub:

1. Open Actions
2. Select Release and Publish
3. Click Run workflow
4. 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.md contains 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.

License

MIT