qianlan717 · Oct 31, 2026 · Oct 31, 2026 · Nov 2, 2026 · Nov 4, 2026 · Nov 4, 2026
diff --git a/core/src/main/scala/org/apache/spark/internal/config/package.scala b/core/src/main/scala/org/apache/spark/internal/config/package.scala
@@ -3087,7 +3087,8 @@ package object config {
         "of the built-in defaults, such as maven central. " +
         "For spark.jars.packages, additional repositories from spark.jars.repositories will " +
         "also be included. " +
-        "Client-resolved Spark Connect Ivy URIs do not use this setting. " +
+        "Client-resolved Spark Connect Ivy URIs use this setting only when the settings file is " +
+        "readable on the client. " +
         "The spark-submit --repositories option applies to submission-time resolution. " +
         "Useful for allowing Spark to resolve artifacts from behind a firewall " +
         "e.g. via an in-house artifact server like Artifactory. " +

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1105,10 +1105,10 @@ Apart from these, the following properties are also available, and may be useful
     For <code>spark.jars.packages</code>, additional repositories from
     <code>spark.jars.repositories</code> will also be included.
     The <code>spark-submit --repositories</code> option applies to submission-time resolution.
-    In Spark Connect, Ivy URIs with a <code>repos</code> query parameter or sent to a server without
-    server-side Maven resolution are resolved by the client and do not use this setting. Other Ivy
-    URIs are resolved by the server, so Maven and Ivy repositories local to the client, such as
-    <code>~/.m2/repository</code> and <code>~/.ivy2.5.2/local</code>, are not searched.
+    Spark Connect JVM clients use the server session's value only if Config RPC exposes it and
+    the file is readable locally; otherwise, they use the built-in defaults.
+    Enable <code>spark.connect.session.serverSideMavenResolution.enabled</code> to resolve Ivy URIs
+    without <code>repos</code> on a supporting server.
     Useful for allowing Spark to resolve artifacts from behind a firewall e.g. via an in-house
     artifact server like Artifactory. Details on the settings file format can be
     found at <a href="http://ant.apache.org/ivy/history/latest-milestone/settings.html">Settings Files</a>.
@@ -3896,6 +3896,14 @@ Command types in proto.</td>
   <td>The interval at which the progress of a query is reported to the client. If the value is set to a negative value the progress reports will be disabled.</td>
   <td>4.0.0</td>
 </tr>
+<tr>
+  <td><code>spark.connect.session.serverSideMavenResolution.enabled</code></td>
+  <td>
+    false
+  </td>
+  <td>When true, the Spark Connect JVM client resolves eligible Maven dependencies on the server when it advertises support. Dependencies that specify repositories are always resolved on the client. When false, the JVM client resolves all Maven dependencies locally. This is a client routing preference, not a server-side enforcement setting.</td>
+  <td>4.4.0</td>
+</tr>
 </table>
 
 ### Security

diff --git a/sql/api/src/main/scala/org/apache/spark/sql/Artifact.scala b/sql/api/src/main/scala/org/apache/spark/sql/Artifact.scala
@@ -94,7 +94,9 @@ private[sql] object Artifact {
     newArtifact(CACHE_PREFIX, "", Paths.get(id), storage)
   }
 
-  def newIvyArtifacts(uri: URI): Seq[Artifact] = {
+  def newIvyArtifacts(uri: URI): Seq[Artifact] = newIvyArtifacts(uri, None)
+
+  def newIvyArtifacts(uri: URI, ivySettingsPath: Option[String]): Seq[Artifact] = {
     implicit val printStream: PrintStream = System.err
 
     val authority = uri.getAuthority
@@ -118,7 +120,10 @@ private[sql] object Artifact {
         Nil
       }
 
-    val ivySettings = MavenUtils.buildIvySettings(Some(repos), None)
+    val ivySettings = ivySettingsPath match {
+      case Some(path) => MavenUtils.loadIvySettings(path, Some(repos), None)
+      case None => MavenUtils.buildIvySettings(Some(repos), None)
+    }
 
     val jars = MavenUtils.resolveMavenCoordinates(
       authority,

diff --git a/sql/api/src/main/scala/org/apache/spark/sql/SparkSession.scala b/sql/api/src/main/scala/org/apache/spark/sql/SparkSession.scala
@@ -562,11 +562,10 @@ abstract class SparkSession extends Serializable with Closeable {
    * Add a single artifact to the current session.
    *
    * Currently it supports local files with extensions .jar and .class and Apache Ivy URIs. Ivy
-   * URIs are resolved using `spark.jars.ivySettings` when it is configured. When using Spark
-   * Connect, Ivy URIs with repositories in the `repos` query parameter, or sent to servers that
-   * do not support server-side Maven resolution, are resolved by the client without the server's
-   * Ivy settings. Otherwise, Ivy URIs are resolved by the server, which does not search Maven or
-   * Ivy repositories local to the client.
+   * URIs use `spark.jars.ivySettings` when configured. Spark Connect resolves them on the client
+   * by default, using the session's settings file if its path is exposed and readable locally.
+   * Enable `spark.connect.session.serverSideMavenResolution.enabled` to resolve URIs without
+   * `repos` on a supporting server.
    *
    * Since 4.4.0, it also supports native data source packages: local files with the extension
    * .sparkpkg, which make the native data sources that they contain available to the session. It
@@ -584,11 +583,7 @@ abstract class SparkSession extends Serializable with Closeable {
    * Add a single artifact to the current session.
    *
    * Currently it supports local files with extensions .jar and .class and Apache Ivy URIs. Ivy
-   * URIs are resolved using `spark.jars.ivySettings` when it is configured. When using Spark
-   * Connect, Ivy URIs with repositories in the `repos` query parameter, or sent to servers that
-   * do not support server-side Maven resolution, are resolved by the client without the server's
-   * Ivy settings. Otherwise, Ivy URIs are resolved by the server, which does not search Maven or
-   * Ivy repositories local to the client.
+   * resolution follows the same settings as `addArtifact(String)`.
    *
    * Since 4.4.0, it also supports native data source packages: local files with the extension
    * .sparkpkg, which make the native data sources that they contain available to the session. It
@@ -657,11 +652,7 @@ abstract class SparkSession extends Serializable with Closeable {
    * Add one or more artifacts to the session.
    *
    * Currently it supports local files with extensions .jar and .class and Apache Ivy URIs. Ivy
-   * URIs are resolved using `spark.jars.ivySettings` when it is configured. When using Spark
-   * Connect, Ivy URIs with repositories in the `repos` query parameter, or sent to servers that
-   * do not support server-side Maven resolution, are resolved by the client without the server's
-   * Ivy settings. Otherwise, Ivy URIs are resolved by the server, which does not search Maven or
-   * Ivy repositories local to the client.
+   * resolution follows the same settings as `addArtifact(String)`.
    *
    * Since 4.4.0, it also supports native data source packages: local files with the extension
    * .sparkpkg, which make the native data sources that they contain available to the session. A