---
updatedAt: 2026-09-25T02:39:00.000Z
agentTools:
siteIndex: https://docs.jfrog.com/llms.txt
projectIndex: https://docs.jfrog.com/artifactory/llms.txt
---
# Use Maven with JFrog CLI
Configure jf mvn and jf mvnw to resolve and deploy Maven artifacts through JFrog Artifactory.
Run Maven builds with Artifactory integration for dependency resolution and build information collection.
This topic covers the following tasks:
* [Configure Maven for Artifactory (`jf mvn-config`)](#configuration-jf-mvn-config)
* [Run Maven builds (`jf mvn`)](#build-jf-mvn)
* [Run Maven Wrapper builds (`jf mvnw`)](#build-jf-mvnw)
## When to Use
Use `jf mvn` if your Java project uses Apache Maven (`pom.xml`) for builds and you want dependencies resolved from Artifactory with build-info collection. Use `jf mvnw` when Native Mode must run the project's checked-in Maven Wrapper instead of `mvn` from `PATH`. For Gradle-based projects, use [`jf gradle`](/docs/jf-gradle).
Running `jf mvn` instead of native `mvn` provides:
* **Artifactory dependency resolution**: Dependencies are fetched from your Artifactory Maven repositories, caching them for your organization
* **Build-info collection**: When using `--build-name` and `--build-number`, the CLI records resolved dependencies and produced artifacts
* **Xray integration**: Build info connects to JFrog Xray for vulnerability scanning of your dependency tree
If you don't need these features, use native `mvn` pointed at Artifactory via `settings.xml`.
**Package Alias (Ghost Frog)**
To run native `mvn` commands without the `jf` prefix, see [Use JFrog CLI Package Alias](/artifactory/docs/jfrog-cli-package-alias).
**Package manager version compatibility**
Before you begin, review [Supported Package Manager Versions](/artifactory/docs/package-manager-compatibility-matrix) for the Maven versions supported and tested with JFrog CLI.
## Prerequisites
* Run `jf mvn-config` in the project directory before the first build.
* Configure a server with `jf config add` or `jf c add`.
* Authentication to Artifactory is required.
* **Java must be in your `PATH` or `JAVA_HOME` must be set.** The `jf mvn` command invokes `java` directly and does not inherit Maven's own Java path. Verify with `java -version` before running `jf mvn`. On macOS with Homebrew, add `export JAVA_HOME=$(brew --prefix openjdk)` to your shell profile.
* If your Artifactory server uses **reference tokens** (non-JWT), configure a username alongside the token: `jf config add --user=`. Without a username, Maven's HTTP client cannot authenticate and you will see a `[Warn]` before every build.
***
## Configuration: jf mvn-config
Generate Maven build configuration for resolving and deploying artifacts through Artifactory. **Run this once per project before your first build.**
**To configure Maven for Artifactory:**
1. Configure a server with `jf config add` or `jf c add` (see [Prerequisites](#prerequisites)).
2. Run `jf mvn-config` with the resolution and/or deployment repository and server flags (see [Non-Interactive Configuration](#non-interactive-configuration)).
### Synopsis
```
jf mvn-config [options]
```
**Aliases:** `mvnc`
### Configuration Options
| Flag | Default | Description |
| --------------------------- | ------- | -------------------------------------------------------------------------------- |
| `--global` | `false` | Apply configuration globally for all projects |
| `--server-id-resolve` | — | Artifactory server ID for dependency resolution |
| `--server-id-deploy` | — | Artifactory server ID for deployment |
| `--repo-resolve-releases` | — | Repository for resolving release dependencies |
| `--repo-resolve-snapshots` | — | Repository for resolving snapshot dependencies |
| `--repo-deploy-releases` | — | Repository for deploying release artifacts |
| `--repo-deploy-snapshots` | — | Repository for deploying snapshot artifacts |
| `--include-patterns` | — | Wildcard patterns for artifacts to include (multiple patterns separated by `, `) |
| `--exclude-patterns` | — | Wildcard patterns for artifacts to exclude (multiple patterns separated by `, `) |
| `--use-wrapper` | `false` | In Wrapped Mode, use the Maven Wrapper |
| `--disable-snapshots` | `false` | Disable snapshot resolution |
| `--snapshots-update-policy` | `daily` | Snapshot update policy |
### Configuration Examples
#### View Help
```bash
jf mvn-config --help
```
#### Non-Interactive Configuration
Configure Maven with non-interactive flags:
```bash
jf mvn-config --server-id-resolve= --repo-resolve-releases= --repo-resolve-snapshots= --server-id-deploy= --repo-deploy-releases= --repo-deploy-snapshots=
```
Where:
* ``: The server ID configured using `jf config add`
* ``: The name of the repository in Artifactory
For example:
```bash
jf mvn-config --server-id-resolve=my-server --repo-resolve-releases=libs-release --repo-resolve-snapshots=libs-snapshot --server-id-deploy=my-server --repo-deploy-releases=libs-release-local --repo-deploy-snapshots=libs-snapshot-local
```
### Why Run Config First?
You must run `jf mvn-config` **before** running `jf mvn`. The config command creates a `.jfrog/projects/maven.yaml` file in your project directory that tells the CLI which Artifactory repositories to use for resolution and deployment. Without it, `jf mvn` does not know where to fetch or deploy artifacts.
If you skip this step, you will see the error: `no config file was found! Before running the 'jf mvn' command on a project for the first time, the project should be configured with the 'jf mvn-config' command`.
**Shortcut**
In CI/CD, pass all flags non-interactively so the config step is fully automated and reproducible.
### Configuration Notes
* **Run once per project**: The configuration is stored in `.jfrog/projects/maven.yaml` in your project directory. You only need to run this once (or when changing repository assignments).
* **Global vs project**: Use `--global` to apply the configuration for all Maven projects on the machine. Without it, the configuration is project-specific.
* **Snapshot policy**: `--snapshots-update-policy` controls how often Maven checks for newer snapshot versions. Values: `always`, `daily` (default), `interval:N` (minutes), `never`.
* **Wrapper support**: In Wrapped Mode, set `--use-wrapper=true` if the project uses the Maven Wrapper. In Native Mode, `jf mvn` never runs the wrapper. Use `jf mvnw` instead. See [Build: jf mvnw](#build-jf-mvnw).
### Expected Output
```
$ jf mvn-config --server-id-resolve=my-server --repo-resolve-releases=libs-release --repo-resolve-snapshots=libs-snapshot --server-id-deploy=my-server --repo-deploy-releases=libs-release-local --repo-deploy-snapshots=libs-snapshot-local
[Info] maven build config successfully created.
```
### How to Verify
After running, confirm the configuration exists:
```bash
cat .jfrog/projects/maven.yaml
```
***
## Build: jf mvn
Run Maven build with Artifactory integration for dependency resolution and build information collection.
**First run**
On the first `jf mvn` invocation, the CLI automatically downloads a build-info-extractor JAR (~10–15 seconds) from `releases.jfrog.io`. Subsequent runs use the cached copy. In air-gapped environments, set `JFROG_CLI_EXTRACTORS_REMOTE` before your first build. See [Downloading the Maven and Gradle Extractor JARs](#downloading-the-maven-and-gradle-extractor-jars).
**To run a Maven build with Artifactory integration:**
1. Run `jf mvn-config` in the project directory if you have not already (see [Configuration](#configuration-jf-mvn-config)).
2. From the project root, run `jf mvn` with your Maven goals and options, adding `--build-name` and `--build-number` when you want build-info (see [Build Examples](#build-examples)).
### Synopsis
```
jf mvn [options]
```
**Aliases:** none
### Arguments
| Argument | Required | Description |
| ------------------- | -------- | ---------------------------------------------------------------------------- |
| `goals-and-options` | Yes | Maven goals and options (for example, `clean install`, `-f path/to/pom.xml`) |
### Build Options
| Flag | Default | Description |
| -------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `--build-name` | — | Build name for build information (requires `--build-number`) |
| `--build-number` | — | Build number for build information (requires `--build-name`) |
| `--project` | — | JFrog Artifactory project key |
| `--module` | — | Optional module name for build information |
| `--detailed-summary` | `false` | Include affected files in the command summary |
| `--threads` | `3` | Number of threads for uploading build artifacts |
| `--insecure-tls` | `false` | Skip TLS certificates verification |
| `--scan` | `false` | Scan all files with Xray on the local file system before upload; skip upload if vulnerabilities are found |
| `--format` | `table` | Output format for the `--scan` option. Accepts `table`, `json`, `simple-json`, or `sarif` |
### Build Examples
#### Build and Publish Build Information
```bash
jf mvn clean install --build-name= --build-number=
```
Where:
* ``: A name for the build (for example, `my-java-app`)
* ``: A number or identifier for the build run (for example, `1`)
For example:
```bash
jf mvn clean install --build-name=my-java-app --build-number=1
```
#### Build with Custom Threads
```bash
jf mvn package --build-name=my-app --build-number=1 --threads=5
```
**Note**
If you have deployment repositories configured, you will see a `[Warn]` before the build: `Deployer repository is configured but Maven goal does not trigger deployment. Only 'install' and 'deploy' goals (including deploy:deploy-file) will deploy artifacts to Artifactory.` This is expected — `package` does not deploy. See [Deploying Maven Artifacts](#deploying-maven-artifacts) for the full goal-to-deploy mapping.
#### Build Without Deploying Artifacts
```bash
jf mvn clean install -Dartifactory.publish.artifacts=false
```
***
## Build: jf mvnw
Run a Maven build through the project's Maven Wrapper with the same Artifactory integration and flags as `jf mvn`. Requires JFrog CLI 2.117.0 or later.
`jf mvnw` runs `mvnw` on macOS and Linux, and `mvnw.cmd` on Windows. Use it when the project pins its Maven version with a checked-in wrapper and Native Mode must use that version instead of whatever `mvn` resolves to on `PATH`.
**To run a Maven build with the project's Maven Wrapper:**
1. Confirm `mvnw` or `mvnw.cmd` exists in the current directory or a parent directory. A standard Maven Wrapper also includes `.mvn/wrapper/maven-wrapper.properties`.
2. For Native Mode wrapper resolution, do not leave `.jfrog/projects/maven.yaml` in the project. See [Native Mode](#native-mode).
3. From the project, run `jf mvnw` with the same goals and options you pass to `jf mvn`.
### Synopsis
```
jf mvnw [options]
```
**Aliases:** none
`jf mvnw` accepts the same [build options](#build-options) as `jf mvn`.
### Wrapper Examples
```bash
jf mvnw clean install
```
```bash
jf mvnw package -DskipTests
```
```bash
jf mvnw clean install --build-name=my-java-app --build-number=1
```
### Native Mode and Wrapped Mode Behavior
The following table describes how `jf mvnw` chooses the Maven executable.
| Mode | How `jf mvnw` chooses Maven |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| Native Mode, with no `.jfrog/projects/maven.yaml` file | Searches upward for `mvnw` or `mvnw.cmd`. If none is found, the command fails. It does not fall back to `mvn` on `PATH`. |
| Wrapped Mode, when `.jfrog/projects/maven.yaml` exists | Behaves like `jf mvn`. Wrapper usage follows `jf mvn-config --use-wrapper`. |
In Native Mode, `jf mvn` always uses `mvn` from `PATH`, even when a wrapper script exists.
When Wrapped Mode is active, the CLI logs: `jf mvnw's wrapper requirement is not respected in legacy (config-file) mode; falling back to the standard jf mvn behavior, governed by the 'useWrapper' setting in the Maven config.`
***
## Important Notes
* **Build-info publishing**: Using `--build-name` and `--build-number` only collects build info. To publish it to Artifactory, run `jf rt build-publish ` afterward.
* **Maven goals**: All standard Maven goals and flags work (`clean`, `install`, `deploy`, `-DskipTests`, `-f`, and others). The CLI wraps the native Maven execution.
* **Thread count**: The `--threads` flag controls parallel upload of build artifacts to Artifactory, not Maven's own `-T` parallelism.
* **Hidden flag — `--module`**: The `--module` flag is functional and collected by the build-info framework, but does not appear in `jf mvn --help` output. It works when passed on the command line alongside `--build-name` and `--build-number`.
## Deploying Maven Artifacts
When you run Maven through JFrog CLI (`jf mvn` or `jf mvnw`), the JFrog Build Info Extractor automatically deploys build artifacts to Artifactory. Unlike standard Maven, where deployment only occurs during the `deploy` phase, the JFrog CLI integration deploys artifacts at the `install` phase or later.
| Maven Goal | Deploys to Artifactory? |
| ---------------------------------------- | ----------------------- |
| `validate`, `compile`, `test`, `package` | No |
| `install` | **Yes** |
| `deploy` | **Yes** |
### Preventing Deployment
**To run Maven through JFrog CLI without deploying artifacts to Artifactory:**
* **Add the publish flag** — Pass `-Dartifactory.publish.artifacts=false` to your goals/options:
```bash
jf mvn clean install -Dartifactory.publish.artifacts=false
```
* **Use an earlier goal** — Run `jf mvn clean package` instead of `install` if you only need to build without deploying.
* **Omit deployment repositories** — When configuring the project with `jf mvn-config`, do not specify `--repo-deploy-releases` or `--repo-deploy-snapshots`. If no deployment repositories are configured, artifacts will not be deployed.
## Native Mode
Maven supports **Native Mode**, which bypasses `jf mvn-config` and all `.jfrog/` YAML configuration. In this mode, no `settings.xml` is injected — you must configure Maven to resolve from Artifactory manually (via Set Me Up). Build-info **is still collected** when `--build-name` and `--build-number` are provided.
Enable with: `export JFROG_RUN_NATIVE=true`
For full setup instructions, per-tool comparison, and when to use each mode, see [Native Mode](/docs/native-mode).
**Known limitation — multi-module projects**
Maven Native Mode does not support multi-module Maven projects (parent POMs with ``). Build-info may be incomplete or incorrect for child modules. Use Wrapped Mode (`jf mvn-config` + `jf mvn`) instead.
In Native Mode, `jf mvn` always uses `mvn` from `PATH`. To run the project's Maven Wrapper, use `jf mvnw`. See [Build: jf mvnw](#build-jf-mvnw).
## Performance Notes
* **Large multi-module projects**: Maven builds with many modules generate significant build-info. The `--threads` flag controls upload parallelism for artifacts, not Maven's own `-T` thread count. Use both for maximum performance.
* **Snapshot resolution frequency**: If builds are slow due to snapshot checks, set `--snapshots-update-policy=never` in `jf mvn-config` during CI builds where snapshot consistency is guaranteed.
* **Network bandwidth**: Dependency resolution speed depends on the network path to Artifactory. Use a local or regional Artifactory instance for best performance.
***
## Environment Variables
| Variable | Default | Description |
| ----------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JFROG_CLI_RELEASES_REPO` | — | Configured Artifactory repository from which to download the build-info-extractor JAR. Format: `/`. The repository should proxy `https://releases.jfrog.io`. Also used by `jf gradle` and `jf audit` (for Maven/Gradle projects). |
| `JFROG_CLI_DEPENDENCIES_DIR` | `$JFROG_CLI_HOME_DIR/dependencies` | Directory to which JFrog CLI's internal dependencies are downloaded. |
| `JFROG_CLI_EXTRACTORS_REMOTE` | — | Alternative to `JFROG_CLI_RELEASES_REPO` for offline environments. Format: `/`. |
***
## Downloading the Maven and Gradle Extractor JARs
For integration with Maven and Gradle, JFrog CLI uses build-info-extractor JAR files. These JARs are downloaded by JFrog CLI from JFrog's distribution (`releases.jfrog.io`) the first time they are needed.
**Air-gapped or offline?** See [Air-Gapped and Offline Setup](/installation/docs/configure-jfrog-platform-in-an-air-gapped-environment) for a step-by-step guide.
**To download extractors through an Artifactory remote repository:**
1. Create a remote Maven repository in Artifactory and name it `extractors`. Configure it to proxy `https://releases.jfrog.io/artifactory/oss-release-local`.
2. Verify that this Artifactory server is configured in JFrog CLI using `jf c show`.
3. Set the `JFROG_CLI_EXTRACTORS_REMOTE` environment variable. The value should be the Server ID followed by a slash and the repository name. For example: `my-rt-server/extractors`.
***
## CI/CD Example: GitHub Actions
**Package Alias (Ghost Frog)**
To run `mvn` without the `jf` prefix, enable Package Alias in `setup-jfrog-cli` and set `JFROG_CLI_GHOST_FROG=true`. If you install the tool **after** the action (for example `setup-java` or `setup-node`), re-pin the alias path to `GITHUB_PATH`. See [Use JFrog CLI Package Alias](/artifactory/docs/jfrog-cli-package-alias#path-priority-and-re-pinning-aliases).
```yaml
# .github/workflows/build.yml
steps:
- uses: actions/checkout@v4
- name: Setup JFrog CLI
uses: jfrog/setup-jfrog-cli@v4
env:
JF_URL: ${{ vars.JF_URL }}
JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
- name: Configure Maven
run: jf mvn-config --server-id-resolve=setup-jfrog-cli-server --repo-resolve-releases=libs-release --repo-resolve-snapshots=libs-snapshot --server-id-deploy=setup-jfrog-cli-server --repo-deploy-releases=libs-release-local --repo-deploy-snapshots=libs-snapshot-local
- name: Build with Maven
run: jf mvn clean install -DskipTests --build-name=my-java-app --build-number=${{ github.run_number }}
- name: Publish build info
run: jf rt build-publish my-java-app ${{ github.run_number }}
```
## Troubleshooting
| Symptom | Cause | Fix |
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `no config file was found` | `jf mvn-config` was not run | Run `jf mvn-config` in the project directory |
| 404 on dependency resolution | Resolution repository does not exist or name is wrong | Verify `--repo-resolve-releases` and `--repo-resolve-snapshots` match existing Artifactory repositories |
| 401 / 403 errors | Invalid credentials or insufficient permissions | Re-run `jf config add` with a valid access token |
| `[Warn] couldn't extract payload from Access Token... reference token... requires a username` | Access token is a reference token (non-JWT). Maven's HTTP client requires basic auth (username + token). | Re-run `jf config add --user=` to add a username to the server config. |
| `Unable to locate a Java Runtime` | `JAVA_HOME` is not set and `java` is not in system `PATH` | Set `JAVA_HOME` to your JDK installation and export it: `export JAVA_HOME=$(brew --prefix openjdk)` (macOS Homebrew) or `export JAVA_HOME=/usr/lib/jvm/java-21` (Linux). Verify with `java -version`. |
| Artifacts deployed at `install` phase unexpectedly | JFrog Build Info Extractor deploys at `install` and later phases | Pass `-Dartifactory.publish.artifacts=false` or use `jf mvn clean package` |
| Build-info shows 0 dependencies | `--build-name` and `--build-number` not passed to `jf mvn` | Add both flags to the Maven command |
| Build-info incomplete or incorrect in Native Mode | Multi-module Maven project (`` in parent POM) | Use Wrapped Mode: run `jf mvn-config` then `jf mvn` (unset `JFROG_RUN_NATIVE`) |
| Native Mode uses system `mvn` instead of wrapper | Expected: `jf mvn` in Native Mode always uses `mvn` from `PATH` | Use `jf mvnw` when you need the Maven Wrapper, or use Wrapped Mode with `jf mvn-config --use-wrapper=true` |
| `mvnw invoked but no Maven Wrapper (mvnw) was found in the current directory or any parent directory` | Native Mode `jf mvnw` did not find `mvnw`. On Windows the message names `mvnw.cmd`. | Add a Maven Wrapper to the project or a parent directory, or run `jf mvn` if you intend to use `mvn` from `PATH`. |
| `jf mvnw` does not require a wrapper and follows `useWrapper` | `.jfrog/projects/maven.yaml` is present, so Wrapped Mode is active | Remove `maven.yaml` for Native Mode wrapper resolution, or set `jf mvn-config --use-wrapper=true` in Wrapped Mode. |
| Extractor JAR download fails | No internet access on build machine | Set `JFROG_CLI_EXTRACTORS_REMOTE` to an Artifactory remote repo proxying `releases.jfrog.io` |
| Snapshot resolution is slow | Default update policy checks daily | Set `--snapshots-update-policy=never` in `jf mvn-config` for CI builds |
| JVM native-access warnings on every build (`WARNING: A restricted method... java.lang.System::load`) | Maven's bundled `jansi` library triggers a restricted native-access warning on Java 21+ | These are Maven warnings, not JFrog CLI errors. Suppress with `export MAVEN_OPTS='--enable-native-access=ALL-UNNAMED'` in your shell profile. |
**Enable debug logging:** `export JFROG_CLI_LOG_LEVEL=DEBUG`
## Frequently Asked Questions
This section provides answers to frequently asked questions about using Maven with JFrog CLI.
##### Q: How do I run Maven builds with jf mvn and build-info?
**A:** Run `jf mvn clean install` (or `deploy`) with `--build-name` and `--build-number`, then publish the build info with `jf rt build-publish`. See [Build: `jf mvn`](#build-jf-mvn).
##### Q: What do I need before using jf mvn with Artifactory?
**A:** You need a Java runtime on your `PATH` or `JAVA_HOME`, a configured JFrog CLI server, and `jf mvn-config` run once in the project directory. See [Prerequisites](#prerequisites).
##### Q: What is the difference between mvn install and mvn deploy for Artifactory deployment?
**A:** Both deploy artifacts to Artifactory through JFrog CLI. Goals earlier than `install`, such as `validate`, `compile`, `test`, and `package`, don't deploy. See [Deploying Maven Artifacts](#deploying-maven-artifacts).
##### Q: How do I run jf mvn without deploying artifacts to Artifactory?
**A:** Pass `-Dartifactory.publish.artifacts=false`, run an earlier goal such as `clean package`, or omit deployment repositories in `jf mvn-config`. See [Preventing Deployment](#preventing-deployment).
##### Q: Does jf mvn support multi-module Maven projects in Native Mode?
**A:** No. Native Mode doesn't support multi-module projects with parent POMs. Use Wrapped Mode (`jf mvn-config` then `jf mvn`) instead. See [Native Mode](#native-mode).
##### Q: How do I use the Maven Wrapper with JFrog CLI?
**A:** In Native Mode, run `jf mvnw` with your Maven goals. Requires JFrog CLI 2.117.0 or later. In Wrapped Mode, run `jf mvn-config --use-wrapper=true`, then `jf mvn`. Package Alias does not intercept `mvnw`. See [Build: jf mvnw](#build-jf-mvnw).
## Related Topics
* [Build Tools Overview](/artifactory/docs/build-tool-commands)
* [Native Mode](/artifactory/docs/native-mode)
* [Use JFrog CLI Package Alias](/artifactory/docs/jfrog-cli-package-alias)
* [Supported Package Manager Versions](/artifactory/docs/package-manager-compatibility-matrix)