Native Mode

JFrog CLI provides two execution modes for package managers: Wrapped Mode (default) and Native Mode (opt-in). This page explains the difference, which tools support Native Mode, and how to configure each one.

This topic covers the following tasks:

• Maven Native Mode
• Gradle Native Mode
• npm Native Mode
• Poetry Native Mode
• Docker Native Mode

Prerequisites

Before using any build-tool command, ensure the following are in place:

Build-Info Flags in Native Mode

The following flags are available on every build-tool command that supports build-info collection. They work in both Wrapped Mode and Native Mode.

--module Flag

The --module flag is used when a single build produces multiple logical components:

jf mvn clean install --build-name=my-app --build-number=1 --module=backend
jf mvn clean install --build-name=my-app --build-number=1 --module=frontend
jf rt build-publish my-app 1 --server-id=<your-server-id>

The resulting build-info for build my-app #1 contains two modules (backend and frontend), each with their own dependency trees.

--project Flag

The --project flag associates the build-info with a JFrog Project — an organizational unit in the JFrog Platform that groups repositories, builds, and security policies.

jf npm install --build-name=my-app --build-number=1 --project=my-team
jf rt build-publish my-app 1 --project=my-team --server-id=<your-server-id>

Wrapped Mode vs Native Mode

Which Tools Support Native Mode?

Native-only tools (build execution always runs native. The table's "Wrapped" concept doesn't apply to how jf <tool> itself runs):

Wrapped-only tools (no Native Mode support):

pip, Pipenv, Twine, Go, NuGet, .NET, Terraform, Ruby — these tools operate exclusively in Wrapped Mode.

Maven Native Mode

When JFROG_RUN_NATIVE=true is set, jf mvn runs Maven without injecting a generated settings.xml or applying .jfrog/projects/maven.yaml. You must configure Maven to resolve from Artifactory yourself using the Artifactory Set Me Up instructions for your Maven repository. The Set Me Up page generates a <server> entry with your Artifactory URL and credentials that you add to your ~/.m2/settings.xml.

To switch Maven to Native Mode when .jfrog/projects/maven.yaml exists:

1. Remove the wrapped-mode project file:

   Bash

   rm .jfrog/projects/maven.yaml

2. Enable Native Mode for the shell session:

   Bash

   export JFROG_RUN_NATIVE=true

Usage

To run a Maven build in Native Mode:

• Run:

  Bash

  export JFROG_RUN_NATIVE=true
  jf mvn clean install --build-name=my-app --build-number=1 --server-id=<your-server-id>

  Where:

  • <your-server-id>: The JFrog CLI server ID from jf config add

  For example:

  Bash

  export JFROG_RUN_NATIVE=true
  jf mvn clean install --build-name=my-app --build-number=1 --server-id=my-server

Expected output

When Native Mode is active (no .jfrog/projects/maven.yaml present), Maven runs directly and build-info is collected after the build completes:

[INFO] BUILD SUCCESS
[Info] Collecting build info for executed command...
[Info] Build info saved locally. Use 'jf rt bp my-app 1' to publish it to Artifactory.

What changes

• No settings.xml injection
• No .jfrog/projects/maven.yaml is read (requires the file to be absent — see the Important callout in this section)
• Build-info is collected after the build completes (post-execution, not via extractor injection)
• All Maven configuration comes from your own settings.xml
• Maven wrapper: If mvnw or mvnw.cmd exists in the project root, Native Mode uses it automatically. Otherwise, the CLI uses mvn from your PATH. There is no --use-wrapper flag in Native Mode — use jf mvn-config --use-wrapper=true in Wrapped Mode when you need explicit wrapper configuration.

Gradle Native Mode

When JFROG_RUN_NATIVE=true is set, jf gradle runs Gradle without injecting the Artifactory Gradle plugin or applying .jfrog/projects/gradle.yaml. You must configure Gradle to resolve from Artifactory yourself using the Artifactory Set Me Up instructions, which generate the repository URL and credential configuration you add to your build.gradle or gradle.properties.

To switch Gradle to Native Mode when .jfrog/projects/gradle.yaml exists:

1. Remove the wrapped-mode project file:

   Bash

   rm .jfrog/projects/gradle.yaml

2. Enable Native Mode for the shell session:

   Bash

   export JFROG_RUN_NATIVE=true

Usage

To run a Gradle build in Native Mode:

• Run:

  Bash

  export JFROG_RUN_NATIVE=true
  jf gradle clean build --server-id=<your-server-id>

  Where:

  • <your-server-id>: The JFrog CLI server ID to use for build-info (required in Native Mode)

  For example:

  Bash

  export JFROG_RUN_NATIVE=true
  jf gradle clean build --server-id=my-server

What changes

• No Artifactory Gradle plugin injection
• No .jfrog/projects/gradle.yaml is read (requires the file to be absent — see the Important callout in this section)
• Build-info is still collected when --build-name and --build-number are provided
• All Gradle configuration comes from your own build scripts

npm Native Mode

When JFROG_RUN_NATIVE=true is set (or the deprecated --run-native flag is used), jf npm delegates entirely to the native npm client and uses your .npmrc for all configuration. You must configure your .npmrc with the Artifactory registry URL and authentication token using the Artifactory Set Me Up instructions for your npm repository.

Usage

To run npm commands in Native Mode:

1. Enable Native Mode for the shell session:

   Bash

   export JFROG_RUN_NATIVE=true

2. Run install or publish (examples):

   Bash

   jf npm install --build-name=my-app --build-number=1
   jf npm publish --build-name=my-app --build-number=1 --server-id=<your-server-id>

   Where:

   • <your-server-id>: The JFrog CLI server ID for publish operations when you have multiple servers configured

   For example:

   Bash

   export JFROG_RUN_NATIVE=true
   jf npm install --build-name=my-app --build-number=1
   jf npm publish --build-name=my-app --build-number=1 --server-id=my-server

When Native Mode is active, the CLI confirms it at the start of execution:

[Info] Running npm in native mode (JFROG_RUN_NATIVE=true)

What changes

• No temporary .npmrc is created by the CLI
• Your own .npmrc is used for all configuration
• Build-info collection still works (as with other tools in Native Mode)
• Publishing uses the native npm publish lifecycle (prepublish, publish, postpublish scripts run normally — no renaming needed)

Poetry Native Mode

When JFROG_RUN_NATIVE=true is set, jf poetry delegates to the native Poetry client without injecting Artifactory configuration or modifying project files. You can run Poetry commands through jf poetry (to benefit from build-info collection) or directly via poetry (without build-info). You must configure Poetry to use the Artifactory repository using the Artifactory Set Me Up instructions for your PyPI repository. The Set Me Up page generates the poetry source add command and credential configuration you add to your project.

Usage

To run Poetry with build-info in Native Mode:

1. Enable Native Mode:

   Bash

   export JFROG_RUN_NATIVE=true

2. Run installs and publishes through jf poetry when you need build-info, or use native poetry when you do not:

   • With build-info:

     Bash

     jf poetry install --build-name=my-app --build-number=1
     jf poetry publish --build-name=my-app --build-number=1

   • Without build-info:

     Bash

     poetry install
     poetry build
     poetry publish -r artifactory

What changes

• No tool.poetry.source entries are injected into pyproject.toml
• No poetry update is called implicitly
• No poetry.lock modifications
• No .jfrog/projects/poetry.yaml is read
• Build-info is still collected when using jf poetry with --build-name and --build-number
• All configuration comes from Poetry's own config and Artifactory Set Me Up

Docker Native Mode

When JFROG_RUN_NATIVE=true is set, jf docker build runs the native Docker build directly instead of the legacy JFrog build flow. Build-info is still collected when --build-name and --build-number are provided. Prerequisites: the Docker daemon must be running (docker info), a JFrog server must be configured with jf config add, and you must be logged in to the Docker registry with docker login <registry> before running these commands. For details, see jf docker.

Usage

To build and push a Docker image in Native Mode:

1. Enable Native Mode, confirm the Docker daemon is running (docker info), and log in to the registry (docker login <registry>).

2. Run build, push, and publish build-info:

   Bash

   export JFROG_RUN_NATIVE=true
   jf docker build -t <registry>/<image>:<tag> . --build-name=my-app --build-number=1
   jf docker push <registry>/<image>:<tag> --build-name=my-app --build-number=1
   jf rt bp my-app 1 --server-id=<your-server-id>

   Where:

   • <registry>: Your Artifactory Docker registry host (for example, acme.jfrog.io)
   • <image>: Image name (for example, docker-local/my-app)
   • <tag>: Image tag (for example, 1.0.0)
   • <your-server-id>: The JFrog CLI server ID for jf rt bp

   For example:

   Bash

   export JFROG_RUN_NATIVE=true
   jf docker build -t acme.jfrog.io/docker-local/my-app:1.0.0 . --build-name=my-app --build-number=1
   jf docker push acme.jfrog.io/docker-local/my-app:1.0.0 --build-name=my-app --build-number=1
   jf rt bp my-app 1 --server-id=my-server

What changes

• Docker build runs via the native Docker client (no legacy JFrog build wrapper)
• Build-info is still collected when --build-name and --build-number are provided
• Push, pull, and scan behave the same in both modes

Supported Client Versions

Recent JFrog CLI versions are forward-compatible with modern package manager clients. The "Max Client" column represents the highest version certified for build-info collection and Native execution without schema errors.

When to Use Which Mode

Use Wrapped Mode when you want:

• Integrated Artifactory resolution with zero manual configuration
• Automatic build-info capture
• Managed repository configuration via JFrog CLI
• Consistent, unified behaviour across machines and CI

Use Native Mode when you need:

• Strict lockfile fidelity (no modifications to lockfiles such as poetry.lock or package-lock.json)
• Zero modification to project metadata files such as pom.xml, pyproject.toml, or settings.xml
• Full compatibility with the upstream package manager's behaviour
• Builds that must be fully deterministic across environments
• Custom or advanced workflows configured directly in the package manager

Environment Variable Reference

When this variable is set to true, it applies to all commands in the current shell session. Unset it or start a new session to return to Wrapped Mode.

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• Build Tools Overview
• Connect a Build Tool to Artifactory with JFrog CLI
• Use Docker with JFrog CLI