Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


Scala Scripting

Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402 (1 ratings)
Rated 5.0 out of 5
Subscribe to updates I use Ammonite

Statistics on Ammonite

Number of watchers on Github 1578
Number of open issues 57
Average time to close an issue 9 days
Main language Scala
Average time to merge a PR 5 days
Open pull requests 41+
Closed pull requests 28+
Last commit almost 2 years ago
Repo Created about 5 years ago
Repo Last Updated almost 2 years ago
Size 58 MB
Organization / Authorlihaoyi
Latest Release1.0.5
Page Updated
Do you use Ammonite? Leave a review!
View open issues (57)
View Ammonite activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating Ammonite for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Ammonite Build Status Build (Windows) Gitter Chat Maven Central Patreon

This is where the code for the Ammonite project lives; Both:

If you want to learn more about Ammonite or how to use it, check out the links above, or ask on the Gitter Channel. The remainder of this document is developer-docs for people who want to work on the Ammonite source code itself.

If you are interested in living more on the edge, we also publish artifacts and the doc-site every commit; the doc-site is available at


And contains instructions on how to download the per-commit executable or depend on the perf-commit maven artifact.

Developer Docs

The layout of the repository is roughly:

  • ops/ is Ammonite-Ops
  • amm/ is Ammonite's core, REPL and script runner
  • shell/ is Ammonite-Shell
  • terminal/ is the JLine re-implementation used by Ammonite-REPL to provide syntax highlighting and multiline editing
  • readme/ is the source code for the Documentation, written in Scalatex.
  • published/ is a synthetic project used for publishing, excluding the readme and integration tests

For more detailed information, check out the internals documentation for high-level overviews of some interesting facets of the codebase

Common Commands

Manual Testing

Although most features should be unit tested, it's still useful to fire up a REPL from the current codebase to see things work (or not). There are a variety of shells you can spin up for testing different things:

  • sbt ~terminal/test:run is useful for manual testing the terminal interaction; it basically contains a minimal echo-anything terminal, with multiline input based on the count of open- and closed-parentheses. This lets you test all terminal interactions without all the complexity of the Scala compiler, classloaders, etc. that comes in repl/

  • sbt ~amm/test:run brings up the Ammonite-REPL using the source code in the repository, and automatically restarts it on-exit if you have made a change to the code. Useful for manual testing both of amm/ as well as ops/, since you can just import ammonite.ops._ and start using them. Note that this does not bring in filesystem utilities like the wd variable, cd! command. You can also pass in the path to a .sc file to run it using Ammonite's script runner

  • sbt ~shell/test:run brings up a fully-loaded shell with all filesystem utilities included: wd, cd!, autocomplete for filesystem paths, and more. This uses readme/resources/example-predef.scala instead of your default predef, for easier experimentation and development.

  • sbt ~integration/test:run runs the trivial main method in the integration subproject, letting you manually test running Ammonite programmatically, whether through run or debug

  • sbt ~integration/test:console brings up a console in the integration subproject, loading Ammonite-REPL as a test console, as described in the readme. Similar to integration/test:run but useful for verifying the different classloader/execution environment we get by starting Ammonite inside the Scala REPL doesn't break things

  • sbt ~amm/test:assembly creates an assembly at amm/target/amm that you can then use to test: start a REPL, run scripts, etc. in a standalone environment without being wrapped in SBT.

Automated Testing

While working on a arbitrary xyz subproject, sbt ~xyz/test runs tests after every change. amm/test can be a bit slow because of the amount of code it compiles, so you may want to specify the test manually via amm/test-only --

  • ops/test tests the filesystem operations, without any REPL present
  • amm/test tests the Ammonite-REPL/Script-runner, without filesystem-shell integration.
  • terminal/test tests the readline re-implementation: keyboard navigation, shortcuts, editing, without any filesystem/scala-repl logic
  • shell/test tests the integration between the standalone ops/ and amm/ projects: features like cd!/wd, path-completion, ops-related pretty-printing and tools
  • integration/test kicks off the integration tests, which bundle amm/ and shell/ into their respective jars and invoke them as subprocesses. Somewhat slow, but exercises all the command-line-parsing stuff that the other unit tests do not exercise, and makes sure that everything works when run from .jars instead of loose class-files


  • Publishing is automatic, controlled by scripts in the ci/ folder.

  • Every commit that lands in master will publish a new unstable version, that you can already use and download. This includes publishing the unstable version to maven central to the snapshot-commit-uploads tag, and updating the documentation-site so it's Unstable Version download instructions to point to it, though the main download/install instructions in the doc-site will not be changed.

  • Every commit that lands in master with a tag will re-publish a stable version to maven central and upload a new versioned release (using the tag as the version) and the doc-site is updated so the main download/install instructions point at the new published stable version.

In general, if you land a change in master, once CI completes (1-2hrs) you should be able to download it via the Unstable Version instructions and make use of your changes standalone or in an SBT project.

Occasionally, the CI job building and publishing one of the above steps flakes and fails, and needs to be re-run through the travis web interface.

Issue Tags

I've started tagging open issues in the issue tracker to try and keep things neat. This is what the various tags mean:

Each issue should only have one of these:

  • bug: this behavior clearly wrong, and needs to be fixed
  • enhancement: something relatively speccable, that can be worked on, finished, and will make Ammonite better
  • wishlist: could be totally awesome, but we're uncertain if it is worth doing at all, what it would look like, or if it will ever reach a finished state.

And possibly:

  • help wanted: I don't have context, hardware, or for some other reason am unlikely to ever do this. But I know people out there care, so one of you should step up and fix it.

Contribution Guidelines

  • All code PRs should come with: a meaningful description, inline-comments for important things, unit tests (positive and negative), and a green build in CI
  • Try to keep lines below 80 characters width, with a hard limit of 100 characters.
  • PRs for features should generally come with something added to the Documentation, so people can discover that it exists
  • Be prepared to discuss/argue-for your changes if you want them merged! You will probably need to refactor so your changes fit into the larger codebase
  • If your code is hard to unit test, and you don't want to unit test it, that's ok. But be prepared to argue why that's the case!
  • It's entirely possible your changes won't be merged, or will get ripped out later. This is also the case for my changes, as the Author!
  • Even a rejected/reverted PR is valuable! It helps explore the solution space, and know what works and what doesn't. For every line in the repo, at least three lines were tried, committed, and reverted/refactored, and more than 10 were tried without committing.
  • Feel free to send Proof-Of-Concept PRs that you don't intend to get merged.
Ammonite open issues Ask a question     (View All Issues)
  • over 3 years Compilation cache not cleared when creating assembly and running with java -cp
  • over 3 years Compiled script fails to find resource
  • over 3 years Ammonite repl gives missing configuration error with akka
  • over 3 years import $file with files that have another extension other than sc
  • over 3 years sourcecode.File() does not return full path to current script
  • over 3 years cannot add a resolver from within a script
  • over 3 years Get the exit status of a command
  • over 3 years Ease to update Ammonite
  • over 3 years Convert `read.iter` and similar functions to use a push-based generator instead
  • over 3 years Some imports fail on the first attempt
  • over 3 years Providing credentials for resolver
  • over 3 years Code runs OK in REPL but fails when compiled as script
  • over 3 years Script arguments can't start with a dash
  • over 3 years java.lang.AbstractMethodError after creating class inheriting from trait
  • over 3 years implicit def should override all previous definitions
  • over 3 years Ivy import of cats library fails and corrupts Ivy Cache
  • over 3 years RuntimeException from REPL predef only after compilation is cached
  • over 3 years Document the r string interpolator
  • over 3 years NullPointerException on fansi.Str$.apply
  • over 3 years Load JDBC drivers in scripts with arguments
  • over 3 years How to load ivy dependencies through a HTTP proxy
  • over 3 years Macro expansion error is breaking during pretty print
  • over 3 years Bytecode not available for classes defined in ammonite repl
  • over 3 years repl won't exit if non-daemon threads still active
  • over 3 years update developer/internals docs to mention gotchas
  • over 3 years Resolve `$file` and `$exec` imports relative to `wd` and not `cwd`
  • over 3 years clearer documentation on how import $file lookup works
  • over 3 years Refactor script-import system to allow pre-compilation without execution
  • over 3 years Path autocompletion doesn't work with '-starting symbol-literals
  • over 3 years IntelliJ support for Ammonite scripts
Ammonite open pull requests (View All Pulls)
  • Capture exceptions and expose them to the REPL as repl.lastException
  • Create Conscript launch configurations
  • Ability to save things defined in REPL to jar - praveens/repl/write jar
  • avoid loading non-jar from load.ivy's classpath to prevent repl blow-up
  • Adding: Load(scalaCode:String, visible: Boolean) + Jar dependency error message
  • Add command line switch("-t") to display time taken for each step to facilitate performance analysis
  • load.module("script.scala") should be instead load.module(cwd / "script.scala")
  • Changes to fix #383 (to get ammonite working with Spark)
  • Updated repl docs to include brew install instructions
  • Implement script level cache
  • add maven central version badge to readme
  • [WIP]Attempt to fix #397
  • Fix + test for #430
  • Allow configuration of SSHD console classloader
  • Use RSA host keys instead of DSA
  • Fix #463
  • upgrade org.apache.sshd sshd-core from 0.14 to 1.3.0 to fix openssh errors
  • Makes `..` work with $file imports as described in docs
  • Fixes NPE/broken REPL on session.load() without save()
  • update sshd
  • Add options to disable Ammonite's defalt argument parser (for scripts)
  • Fix #507 Suppress stack trace for parse error exceptions
  • Show newly available packages when loading dependencies, addresses #245
  • Various improvements to ammonite-sshd:
  • Set JLineFrontEnd and Colors.BlackWhite for Windows
  • add maven resolver via jboss shrinkwrap
  • #460 - Read env proxy settings.
  • Pass unmodified arguments to the interpreter
  • Fix import file docs to reflect changes to parent dir introduced in 0.7.2
  • Shade coursier / scalaz / scala-xml
  • use openjdk7 instead of oraclejdk7
  • Class wrapper for Java serialization friendliness
  • Update sbt and plugins
  • [WIP]Remove tput from terminal dependencies
  • [WIP] Interactive processes
  • Jitpack and optional dependencies
  • Dependency updates
  • Clipboard operations: xclip or pbcopy/pbpaste style operations.
  • autocomplete: blacklisted anything that comes from Any
  • Upgrade jline to 2.14.5
  • Empty welcome banner should not be printed
Ammonite questions on Stackoverflow (View All Questions)
  • How to use scala-js in the ammonite shell (amm)
Ammonite list of languages used
Ammonite latest release notes
1.0.5 1.0.5

1.0.4 1.0.4

1.0.3 1.0.3

Other projects in Scala