Page tree
Skip to end of metadata
Go to start of metadata


To simplify access to different repositories, Artifactory allows you to define a virtual repository which is a collection of local, remote and other virtual repositories accessed through a single logical URL.

A virtual repository hides the access details of the underlying repositories letting users work with a single, well-known URL. The underlying participating repositories and their access rules may be changed without requiring any client-side changes.

The main features supported by a virtual repository are:

  1. Nesting
  2. "Includes" and "Excludes" patterns
  3. Automatic removal of repository references

Setting Up

In  the Admin tab go to Configuration | Repositories. In the Virtual Repositories section click the "New" button to display the New Virtual Repository dialog.

Page Contents

New Virtual Repository Dialog

  1. Define the common settings of the Basic Settings tab. For details please refer to Common Settings.
  2. In the Repositories section, from the list of Available Repositories, select the repositories you want to include in the new virtual repository and move them to the Selected Repositories list.

The Resolved Repositories section displays the effective list of actual repositories included in this virtual repository. If any of the available repositories you have selected are themselves virtual repositories, then the Resolved Repositories section will display the local and remote repositories included within them. The Resolved Repository list is automatically updated in case any of the nested virtual repositories change.

The search/resolution order when requesting artifacts from a virtual repository is always:

  1. Local repositories
  2. Remote repository caches
  3. Remote repositories themselves.


Nesting is a unique feature in Artifactory and facilitates more flexibility in using virtual repositories.

You should take care not to create an "infinite loop" of nested repositories. Artifactory analyzes the internal composition of virtual repositories and will issue a warning if the virtual repository can not be resolved due to invalid nesting.

Using Includes and Excludes Patterns

The ability to define and Includes Pattern and an Excludes Pattern for virtual repositories (especially when nesting is used) provides a powerful tool you can use to manage artifact requests in your organization.

For example, your organization may have its own artifacts which are hosted both internally in a local repository, but also in a remote repository. For optimal performance, you would want these artifacts to be accessed from the local repository rather than from the remote one. To enforce this policy, you can define a virtual repository called "remote-repos" which includes the full set of remote repositories accessed by your organization, and then specify an Excludes Pattern with your organization's groupID. in this way, any attempt to access your internal artifact from a remote repository would be rejected.

Consider another example in which you wish to define a virtual repository for your developers, however you wish to keep certain artifacts hidden from them. This could be achieved by defining an Excludes Pattern based on groupId, source or version.

Advanced Settings

The Advanced Settings tab lets you manage the virtual repository layout, access from other instances of Artifactory, security and cache handling.

Virtual Repository Advanced Settings

Repository Layout

The layout used to store and identify modules

Artifactory Requests Can Retrieve Remote Artifacts

An Artifactory instance may request artifacts from a virtual repository in another Artifactory instance. This checkbox specifies whether the virtual repository should search through remote repositories when trying to resolve an artifact requested by another Artifactory instance. For example, you can use this feature when Artifactory is deployed in a mesh (grid) architecture, and you do not want all remote instances of Artifactory to act as proxies for other Artifactory instances.

To control resolution of remote artifacts for other Artifactory instances for the global virtual repository repo, you need to use the artifactory.artifactoryRequestsToGlobalCanRetrieveRemoteArtifacts system property, which is set to false by default.

Cleanup Repository References in POMs

Public POMs may include direct references to external repositories. If either of the below code samples are present in the POM, Maven dynamically adds an external repository URL to the build which circumvents Artifactory.


A client side solution for this is to use mirrorOf. For details please refer to Additional "Mirror-any" Setup.

This setting gives you the ability to ensure Artifactory is the sole provider of Artifacts in your system by automatically cleaning up the POM file. The three values available for this setting are:

Discard Active References

Removes repository elements that are declared directly under project or under a profile in the same POM that is activeByDefault

Discard Any References

Removes all repository elements regardless of whether they are included in an active profile or not


Does not remove any repository elements declared in the POM

Key Pair

A named key-pair to use for automatically signing artifacts.

Please refer to WebStart and Jar Signing.

Zap Caches

Clears all caches stored at the virtual repository level (transformed POMs, JNLP files, merged indexes etc.)

Pre-defined Repositories

Artifactory comes with a set of pre-defined virtual repositories, which reflect binary management best practices as follows.


Aggregation of all remote repositories


libs-releases-local, ext-releases and remote-repos


plugins-releases-local, ext-releases and remote-repos


libs-snapshots-local, ext-snapshots-local, remote-repos


plugins-snapshots-local, ext-snapshots-local, remote-repos


The default global repository

The Default Global Repository

Artifactory defines a default global virtual repository which effectively aggregates all other repositories at the following URL: <host>:<port>/artifactory/repo.

By configuring Maven with this URL, any request for an artifact will go through Artifactory which will search through all of the local and remote repositories defined in the system.

From v3.2, you can disable Artifactory from creating the Default Global Repository by setting in the Artifactory System Properties.



  • No labels