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.

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.

Note: --build-name and --build-number must always be provided together. If you supply one without the other, the CLI returns an error.

--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

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

Note: The --module flag is functional for all build-tool commands. For some commands (Maven, Gradle), it does not appear in jf <tool> --help output but still works when passed on the command line.

--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

Wrapped Mode vs Native Mode

Which Tools Support Native Mode?

Native-only tools (no wrapped mode; no *-config command):

Wrapped-only tools (no Native Mode support):

Yarn, pnpm, 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.

Usage

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

What changes

• No settings.xml injection
• No .jfrog/projects/maven.yaml is read
• Build-info is still collected when --build-name and --build-number are provided
• All Maven configuration comes from your own settings.xml

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 include applying the Artifactory Gradle plugin and configuring repository URLs and credentials in your build script or gradle.properties.

Usage

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

Note: In Gradle Native Mode, pass --server-id to specify which configured server to use. Without it, the CLI uses the default server.

What changes

• No Artifactory Gradle plugin injection
• No .jfrog/projects/gradle.yaml is read
• 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.

Usage

export JFROG_RUN_NATIVE=true

# Install
jf npm install --build-name=my-app --build-number=1

# Publish
jf npm publish --build-name=my-app --build-number=1

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)

Deprecation notice: The --run-native flag is deprecated. Use export JFROG_RUN_NATIVE=true instead.

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.

Usage

export JFROG_RUN_NATIVE=true

# Install with build-info collection
jf poetry install --build-name=my-app --build-number=1

# Or install directly (no build-info)
poetry install

# Publish with build-info collection
jf poetry publish --build-name=my-app --build-number=1

# Or publish directly (no build-info)
poetry build
poetry publish -r artifactory

Note: In Native Mode, you can use either jf poetry install (which delegates to native Poetry and collects build-info when --build-name/--build-number are provided) or poetry install directly (no build-info). Poetry must be configured via Artifactory's Set Me Up instructions for both approaches.

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. A server must be configured with jf config add and you must be logged in to the Docker registry before using Docker Native Mode. For details, see jf docker.

Usage

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

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

JFrog CLI (v2.92.0) is 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.

Notes:

• Yarn 4.x is not supported.
• pnpm has config-only support; no jf pnpm run command; no build-info collection.
• Docker BuildX supports Docker engine up to v28 for multi-platform builds.
• Go --no-fallback default is true (VCS fallback disabled by default).

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 poetry.lock, package-lock.json, etc.)
• Zero modification to project metadata (pom.xml, pyproject.toml, settings.xml, etc.)
• 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

Frequently Asked Questions

How do I enable Native Mode?

Set the environment variable JFROG_RUN_NATIVE=true before running any jf <tool> command. This applies to all supported tools in the current shell session. Unset it or open a new terminal to return to Wrapped Mode.

Does Native Mode still collect build-info?

Yes. When you run commands through jf <tool> with --build-name and --build-number, build-info is collected in both Wrapped and Native Mode. If you run the native tool directly (e.g., npm install without the jf prefix), no build-info is collected.

Which tools support Native Mode?

Maven, Gradle, npm, Poetry, and Docker support both Wrapped and Native Mode. Helm and Conan are native-only (no wrapped mode). All other tools (Yarn, pnpm, pip, Pipenv, Twine, Go, NuGet, .NET, Terraform, Ruby) operate exclusively in Wrapped Mode.

Will Native Mode modify my lockfiles or project files?

No. Native Mode never modifies poetry.lock, package-lock.json, pyproject.toml, settings.xml, or any other project file. This is the primary reason to choose Native Mode over Wrapped Mode.

Can I use Native Mode for some tools and Wrapped Mode for others?

JFROG_RUN_NATIVE=true applies to all supported tools in the session. To mix modes, set the variable only before the commands that should run natively, then unset it before wrapped commands.

Related Topics

• Build Tools Overview — Capabilities matrix and tool reference
• Native Mode — Supported packages with Native Mode

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.