This page provides assistance writing the code that defines the work of an action. To use external libraries or reuse code between projects, see SbtPlugins. You can also directly put libraries in project/build/lib and they can be used from your project definition.

Error Handling

This section describes error handling in sbt. When you create a task, you pass code that returns None if the action executes normally or Some(errorMessage) if an error occurs. This is the way sbt works with errors internally and how it indicates recoverable errors when you use utility methods. Note that if you throw an exception in your code, sbt will handle it.

There are methods in sbt.Control for working with code that can throw exceptions.

File Utilities

sbt includes several methods for dealing with the filesystem in sbt.FileUtilities. Their capabilities are described below. The API documentation describes the details of using the methods.

Jar/Zip/GZip Files

FileUtilities contains methods to create jar, zip or gzip files and for unzipping files. You can unzip from a Path, URL, File, or InputStream and you can optionally filter the files that are extracted using a NameFilter. You can jar, zip, or gzip the files selected by a PathFinder and optionally descend into directories recursively, which is useful if you just want to specify the directories to archive. (See Path for details on Path, PathFinder and NameFilter).


This is not in FileUtilities, but is in sbt.Pack. You can pack and unpack a jar file with either default options or explicitly specified options as given in the java.util.jar.Pack200.Packer class.

Signing Jars

This is not in FileUtilities, but is in sbt.SignJar. It signs or verifies a jar file using the jarsigner executable, which must be on the system path.


There are several methods for copying files and data. You can transfer data from an InputStream to an OutputStream and optionally close the InputStream on completion. You can download data from a URL to a File. You can copy a single file or a single directory (recursively). There are also methods to copy a list of files to a directory, optionally flattening the file hierarchy in the process. Additionally, there is a method to mirror/synchronize the contents of two directories.

Creating Directories and Files

There are methods to create a directory and all parent directories and to "touch" a file (create it if it doesn't exist or update its last modified time if it does).

Removing Directories and Files

There is a method to recursively delete directories and files.

Temporary Directories

There is a method to create a temporary directory and a method to execute code using a temporary directory that is automatically deleted after the code completes.

General I/O

There are methods to read from, write to, and append to files, streams, and readers/writers and let FileUtilities open and close the streams, readers, or writers. There are convenience methods to read or write text or an array of bytes to or from a File.

Access to Jars

There are methods to get the jar file or directory containing a given class.