Groovy @Grab

last modified October 15, 2026

The @Grab annotation downloads a library from a Maven repository when the script runs, then adds it to the classpath. It is a convenient way to use a third-party library in a standalone script without a build file. This tutorial shows how to declare dependencies, use the libraries, and handle versions and repositories.

Declaring a Dependency

Place @Grab before the import statements that use the library. The argument uses the Maven coordinates in the form group:artifact:version.

GrabBasic.groovy

@Grab('org.apache.commons:commons-lang3:3.14.0')
import org.apache.commons.lang3.StringUtils

println StringUtils.capitalize("groovy")
println StringUtils.reverse("grab")

The first run downloads the Commons Lang jar and its dependencies into the local Grape cache, which is usually ~/.groovy/grapes. Later runs reuse the cached files, so they start much faster and work offline.

Named Arguments

The long form lists the group, module, and version as named arguments. It reads better when the coordinates are generated or when you want to add a classifier.

GrabNamed.groovy

@Grab(group='org.apache.commons', module='commons-text', version='1.11.0')
import org.apache.commons.text.WordUtils

println WordUtils.capitalizeFully("hello grab world")

The named form and the string form are equivalent, and both use the same cache and resolution rules. This example uses commons-text, a different library from the commons-lang3 used earlier.

Using Several Dependencies

Each @Grab annotation adds one library. Annotations can be placed on separate lines before the imports that need them.

GrabMultiple.groovy

@Grab('org.apache.commons:commons-lang3:3.14.0')
@Grab('commons-io:commons-io:2.15.1')
import org.apache.commons.lang3.StringUtils
import org.apache.commons.io.FileUtils

println StringUtils.isBlank("   ")
println FileUtils.byteCountToDisplaySize(2048)

StringUtils.isBlank returns true for whitespace-only strings. FileUtils.byteCountToDisplaySize formats a byte count, so 2048 bytes prints as 2 KB.

Adding a Repository

By default, Grab searches Maven Central. For a private or company repository, add it with @GrabResolver. The name and root URL are required.

GrabResolver.groovy

@GrabResolver(name='central-mirror', root='https://repo1.maven.org/maven2/')
@Grab('org.apache.commons:commons-lang3:3.14.0')
import org.apache.commons.lang3.math.NumberUtils

println NumberUtils.isCreatable("12.5")
println NumberUtils.isCreatable("twelve")

The resolver above points to Maven Central, so the example works as written. In a real project, replace the URL with your repository address. Credentials should come from the environment, not from the script file.

Limitations

Grab needs network access the first time a library is requested.
Grab is for scripts. For applications, use Maven or Gradle so that builds are reproducible.
Pinning exact versions avoids surprises when a repository publishes new releases.

Best Practices

Pin versions: Always specify the exact version, such as 3.14.0.
Keep scripts small: Move anything large into a proper project with a build file.
Keep secrets out: Read repository credentials from environment variables, never from the script.
Check the cache: If a download fails, delete the artifact under ~/.groovy/grapes and retry.

Source

Groovy Grape Documentation | Groovy AST Transformations

@Grab brings a library into a script with one line. It is ideal for quick tools and experiments, and a build tool is the better choice for anything that must be reproduced exactly.

Author

My name is Jan Bodnar, and I am a passionate programmer with many years of programming experience. I have been writing programming articles since 2007. So far, I have written over 1400 articles and 8 e-books. I have over eight years of experience in teaching programming.

List all Groovy tutorials.

Ebooks