HomeDocs
DocsCommunityTestimonialsUsersGitHubTwitterBlogJobsTermsPrivacyCookies
TermsPrivacyCookies
Hey! These docs are for version 2.10, which is no longer officially supported. Click here for the latest version, 2.18!


There are two ways to include asset files in your project: `resource` and `file` targets.

## `resources`

A [`resource`](🔗) target is for files that are members of code packages, and are loaded via language-specific mechanisms, such as Python's `pkgutil.get_data()` or Java's `getResource()`.

Pants will make resources available on the appropriate runtime path, such as Python's `PYTHONPATH` or the JVM classpath. Resources can be loaded directly from a binary in which they are embedded, such as a Pex file, without first unpacking it.

To reduce boilerplate, the [`resources`](🔗) target generates a `resource` target per file in the `sources` field.

For example, to load resources in Python:



[Source root](🔗) stripping applies to resources, just as it does for code. In the example above, Python loads the resource named `project/config`, rather than `src/python/project/config.json`.

## `files`

A `file` target is for loose files that are copied into the chroot where Pants runs your code. You can then load these files through direct mechanisms like Python's `open()` or Java's `FileInputStream`. The files are not associated with a code package, and must be extracted out of a deployed archive file before they can be loaded.

To reduce boilerplate, the [`files`](🔗) target generates a `file` target per file in the `sources` field.

For example, to load loose files in Python:



Note that we open the file with its full path, including the `src/python` prefix.

`file` targets are not included with binaries like `pex_binary`

Pants will not include dependencies on `file` / `files` targets when creating binaries like `pex_binary` and `python_awslambda` via `./pants package`. Filesystem APIs like Python's `open()` are relative to the current working directory, and they would try to read the files from where the binary is executed, rather than reading from the binary itself.

Instead, use `resource` / `resources` targets or an `archive` target.

## When to use each asset target type

### When to use `resource`

Use `resource` / `resources` for files that are associated with (and typically live alongside) the code that loads them. That code's target (e.g. `python_source`) should depend on the `resource` target, ensuring that code and data together are embedded directly in a binary package, such as a wheel, Pex file or AWS Lambda.

### When to use `file`

Use `file` / `files` for files that aren't tightly coupled to any specific code, but need to be deployed alongside a binary, such as images served by a web server.

When writing tests, it is also often more convenient to open a file than to load a resource.

Column Title
`resource``file`
**Runtime path**Relative to source rootRelative to repo root
**Loading mechanism**Language's package loader, relative to packageLanguage's file loading idioms, relative to repo root
**Use with**Targets that produce binaries, such as `pex_binary`, `python_distribution`, `python_awslambda`.`archive` targets, tests

## `relocated_files`

When you use a `file` target, Pants will preserve the path to the files, relative to your build root. For example, the file `src/assets/logo.png` in your repo would be under this same path in the runtime chroot.

However, you may want to change the path to something else. For example, when creating an `archive` target and setting the `files` field, you might want those files to be placed at a different path in the archive; rather than `src/assets/logo.png`, for example, you might want the file to be at `imgs/logo.png`.

You can use the `relocated_files` target to change the path used at runtime for the files. Your other targets can then add this target to their `dependencies` field, rather than using the original `files` target:



You can use an empty string in the `src` to add to an existing prefix and an empty string in the `dest` to strip an existing prefix.

If you want multiple different re-mappings for the same original files, you can define multiple `relocated_files` targets.

The `relocated_files` target only accepts `file` and `files` targets in its `files_targets` field. To relocate where other targets like `resource` and `python_source` show up at runtime, you need to change where that code is located in your repository.

## `archive`: create a `zip` or `tar` file

Running `./pants package` on an `archive` target will create a zip or tar file with built packages and/or loose files included. This is often useful when you want to create a binary and bundle it with some loose config files.

For example:



The format can be `zip`, `tar`, `tar.xz`, `tar.gz`, or `tar.bz2`.

The `packages` field is a list of targets that can be built using `./pants package`, such as `pex_binary`, `python_awslambda`, and even other `archive` targets. Pants will build the packages as if you had run `./pants package`. It will include the results in your archive using the same name they would normally have, but without the `dist/` prefix.

The `files` field is a list of `file`, `files`, and `relocated_files` targets. See [resources](🔗) for more details.

You can optionally set the field `output_path` to change the generated archive's name.