jvm_options.html

<!DOCTYPE html>
<html lang="en">

<!--
  Copyright 2014 Pants project contributors (see CONTRIBUTORS.md).
  Licensed under the Apache License, Version 2.0 (see LICENSE).
-->

<head>
  <meta charset="utf-8"/>
  <title>Specify JVM Options</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="shortcut icon" href="pants-logo.ico">
  <!-- In case this is a "test publish", tell search engines where real version lives: -->
  <link rel="canonical" href="http://pantsbuild.org/jvm_options.html">

  <link rel="stylesheet" href="bootstrap-custom.min.css">
  <link rel="stylesheet" href="bootstrap-custom-theme.min.css">
  <link rel="stylesheet" href="docsite.css">
</head>

<body>

<div class="header">
  <nav class="navbar navbar-default navbar-static-top">
    <div class="container">
      <div class="navbar-header">
        <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
          <span class="sr-only">Toggle navigation</span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand navbar-brand-img" href="index.html">
          <img src="pants-logo.ico" alt="[pantsbuild logo]">
        </a>
        <a class="navbar-brand" href="index.html">
          Pants v1
        </a>
      </div>
      <div id="navbar" class="navbar-collapse collapse">
        <ul class="nav navbar-nav navbar-right">
          <li><a href="/">Docs</a></li>
          <li><a href="community.html">Community</a></li>
          <li><a href="https://www.github.com/pantsbuild/pants">GitHub</a></li>
          <li>
            <form class="navbar-form navbar-left search" role="search" action="https://www.google.com/search">
              <div class="form-group">
                <input type="text" name="as_q" class="form-control query" placeholder="Search">
                <input name="as_sitesearch" value="pantsbuild.org" type="hidden">
              </div>
            </form>
          </li>
        </ul>
      </div><!--/.nav-collapse -->
    </div>
    <div class="deprecated">Pants v1 is no longer maintained. See <a href="https://www.pantsbuild.org/">here</a> for the Pants v2 documentation.</div>
  </nav>
</div>

<div class="page">

  <div class="container-fluid">
    <div class="row">

      <div class="col-md-1">
      </div>

      <div class="col-md-2">
        <div class="site-toc">
          <ul>
                  <li class="toc-h1 toc-heading">
                    Getting Started
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="install.html">Installing Pants</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="setup_repo.html">Setting Up Pants</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="first_tutorial.html">Tutorial</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="common_tasks.html">Common Tasks</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="orgs.html">Pants for Organizations</a>
                  </li>
                  <li class="toc-h1 toc-heading">
                    Pants Basics
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="why_use_pants.html">Why Use Pants?</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="first_concepts.html">Pants Concepts</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="build_files.html">BUILD files</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="target_addresses.html">Target Addresses</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="3rdparty.html">Third-Party Dependencies</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="options.html">Pants Options</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="invoking.html">Invoking Pants</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="reporting_server.html">Reporting Server</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="ide_support.html">IDE Support</a>
                  </li>
                <li class="toc-h1">
                  <a class="sidebar-nav-heading" class="toc-drop" data-toggle="collapse" href="#JVM-Support" aria-expanded="false" aria-controls="JVM-Support">JVM Support<span class="caret"></span></a>
                    <ul class="collapse sidebar-nav sidebar-submenu" id="JVM-Support">
                        <li class="toc-h1 toc-link ">
                          <a href="jvm_projects.html">JVM Projects with Pants</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="3rdparty_jvm.html">JVM Dependency Management</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="scala.html">Scala Support</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="publish.html">Publishing Artifacts</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="from_maven.html">Pants for Maven Experts</a>
                        </li>
                    </ul>
                </li>
                <li class="toc-h1">
                  <a class="sidebar-nav-heading" class="toc-drop" data-toggle="collapse" href="#Python-Support" aria-expanded="false" aria-controls="Python-Support">Python Support<span class="caret"></span></a>
                    <ul class="collapse sidebar-nav sidebar-submenu" id="Python-Support">
                        <li class="toc-h1 toc-link ">
                          <a href="python_readme.html">Python Projects with Pants</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="3rdparty_py.html">Python 3rdparty Pattern</a>
                        </li>
                    </ul>
                </li>
                  <li class="toc-h1 toc-link ">
                    <a href="go_readme.html">Go support for Pants</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="node_readme.html">Node.js Support</a>
                  </li>
                  <li class="toc-h1 toc-heading">
                    Code &amp; Doc Generation
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="thrift_deps.html">Thrift</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="grpcio_gen.html">Python gRPC + protobufs</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="page.html">Markdown</a>
                  </li>
                  <li class="toc-h1 toc-heading">
                    Getting Help
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="tshoot.html">Troubleshooting</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="community.html">Community</a>
                  </li>
                  <li class="toc-h1 toc-heading">
                    Reference
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="build_dictionary.html">Pants BUILD Dictionary</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="options_reference.html">Pants Reference</a>
                  </li>
                <li class="toc-h1">
                  <a class="sidebar-nav-heading" class="toc-drop" data-toggle="collapse" href="#Release-Notes" aria-expanded="false" aria-controls="Release-Notes">Release Notes<span class="caret"></span></a>
                    <ul class="collapse sidebar-nav sidebar-submenu" id="Release-Notes">
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.30.x.html">1.30.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.29.x.html">1.29.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.28.x.html">1.28.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.27.x.html">1.27.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.26.x.html">1.26.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.25.x.html">1.25.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.24.x.html">1.24.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.23.x.html">1.23.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.22.x.html">1.22.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.21.x.html">1.21.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.20.x.html">1.20.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.19.x.html">1.19.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.18.x.html">1.18.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.17.x.html">1.17.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.16.x.html">1.16.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.15.x.html">1.15.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.14.x.html">1.14.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.13.x.html">1.13.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.12.x.html">1.12.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.11.x.html">1.11.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.10.x.html">1.10.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.9.x.html">1.9.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.8.x.html">1.8.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.7.x.html">1.7.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.6.x.html">1.6.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.5.x.html">1.5.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.4.x.html">1.4.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.3.x.html">1.3.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.2.x.html">1.2.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.1.x.html">1.1.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.0.x.html">1.0.x Stable Releases</a>
                        </li>
                    </ul>
                </li>
                  <li class="toc-h1 toc-heading">
                    Developer
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="dev.html">Pants Developer Center</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="export.html">Export Format</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="architecture.html">Architecture</a>
                  </li>
                  <li class="toc-h1 toc-heading">
                    Blogs
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="coursier_migration.html">Twitter&#x27;s Coursier Migration</a>
                  </li>
          </ul>
        </div> <!-- site-toc -->
      </div>

      <div class="col-md-8">
        <div class="content">

          <div class="mainflow">
              <nav class="pagetoc">
                <ul>
                    <li class="toc-h1"><a href="#problem">Problem</a></li>
                    <li class="toc-h1"><a href="#solution">Solution</a></li>
                    <li class="toc-h1"><a href="#discussion">Discussion</a></li>
                    <li class="toc-h1"><a href="#see-also">See Also</a></li>
                </ul>
              </nav>

            <!-- main content start -->
            <!-- generated by pants! -->
<style>
.codehilite .hll { background-color: #ffffcc }
.codehilite  { background: #f0f0f0; }
.codehilite .c { color: #60a0b0; font-style: italic } /* Comment */
.codehilite .err { border: 1px solid #FF0000 } /* Error */
.codehilite .k { color: #007020; font-weight: bold } /* Keyword */
.codehilite .o { color: #666666 } /* Operator */
.codehilite .ch { color: #60a0b0; font-style: italic } /* Comment.Hashbang */
.codehilite .cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */
.codehilite .cp { color: #007020 } /* Comment.Preproc */
.codehilite .cpf { color: #60a0b0; font-style: italic } /* Comment.PreprocFile */
.codehilite .c1 { color: #60a0b0; font-style: italic } /* Comment.Single */
.codehilite .cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */
.codehilite .gd { color: #A00000 } /* Generic.Deleted */
.codehilite .ge { font-style: italic } /* Generic.Emph */
.codehilite .gr { color: #FF0000 } /* Generic.Error */
.codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.codehilite .gi { color: #00A000 } /* Generic.Inserted */
.codehilite .go { color: #888888 } /* Generic.Output */
.codehilite .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
.codehilite .gs { font-weight: bold } /* Generic.Strong */
.codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.codehilite .gt { color: #0044DD } /* Generic.Traceback */
.codehilite .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
.codehilite .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
.codehilite .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
.codehilite .kp { color: #007020 } /* Keyword.Pseudo */
.codehilite .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
.codehilite .kt { color: #902000 } /* Keyword.Type */
.codehilite .m { color: #40a070 } /* Literal.Number */
.codehilite .s { color: #4070a0 } /* Literal.String */
.codehilite .na { color: #4070a0 } /* Name.Attribute */
.codehilite .nb { color: #007020 } /* Name.Builtin */
.codehilite .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
.codehilite .no { color: #60add5 } /* Name.Constant */
.codehilite .nd { color: #555555; font-weight: bold } /* Name.Decorator */
.codehilite .ni { color: #d55537; font-weight: bold } /* Name.Entity */
.codehilite .ne { color: #007020 } /* Name.Exception */
.codehilite .nf { color: #06287e } /* Name.Function */
.codehilite .nl { color: #002070; font-weight: bold } /* Name.Label */
.codehilite .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
.codehilite .nt { color: #062873; font-weight: bold } /* Name.Tag */
.codehilite .nv { color: #bb60d5 } /* Name.Variable */
.codehilite .ow { color: #007020; font-weight: bold } /* Operator.Word */
.codehilite .w { color: #bbbbbb } /* Text.Whitespace */
.codehilite .mb { color: #40a070 } /* Literal.Number.Bin */
.codehilite .mf { color: #40a070 } /* Literal.Number.Float */
.codehilite .mh { color: #40a070 } /* Literal.Number.Hex */
.codehilite .mi { color: #40a070 } /* Literal.Number.Integer */
.codehilite .mo { color: #40a070 } /* Literal.Number.Oct */
.codehilite .sa { color: #4070a0 } /* Literal.String.Affix */
.codehilite .sb { color: #4070a0 } /* Literal.String.Backtick */
.codehilite .sc { color: #4070a0 } /* Literal.String.Char */
.codehilite .dl { color: #4070a0 } /* Literal.String.Delimiter */
.codehilite .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
.codehilite .s2 { color: #4070a0 } /* Literal.String.Double */
.codehilite .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
.codehilite .sh { color: #4070a0 } /* Literal.String.Heredoc */
.codehilite .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
.codehilite .sx { color: #c65d09 } /* Literal.String.Other */
.codehilite .sr { color: #235388 } /* Literal.String.Regex */
.codehilite .s1 { color: #4070a0 } /* Literal.String.Single */
.codehilite .ss { color: #517918 } /* Literal.String.Symbol */
.codehilite .bp { color: #007020 } /* Name.Builtin.Pseudo */
.codehilite .fm { color: #06287e } /* Name.Function.Magic */
.codehilite .vc { color: #bb60d5 } /* Name.Variable.Class */
.codehilite .vg { color: #bb60d5 } /* Name.Variable.Global */
.codehilite .vi { color: #bb60d5 } /* Name.Variable.Instance */
.codehilite .vm { color: #bb60d5 } /* Name.Variable.Magic */
.codehilite .il { color: #40a070 } /* Literal.Number.Integer.Long */
</style>
<h1 id="specify-jvm-options">Specify JVM Options</h1>
<h2 id="problem">Problem</h2>
<p>You need to specify command-line options for the JVM when running a Scala or Java goal, e.g. to set GC options, memory limits, enable debugging, etc.</p>
<p>Examples of JVM options can be found <a href="https://docs.oracle.com/cd/E13150_01/jrockit_jvm/jrockit/jrdocs/refman/optionX.html">here</a>.</p>
<h2 id="solution">Solution</h2>
<p>Use the <code>--jvm-run-jvm-options</code> flag to pass the options. Here's an example:</p>
<div class="codehilite"><pre><span></span>$ ./pants run my-jvm-project:bin --jvm-run-jvm-options<span class="o">=</span><span class="s1">'-XX:+UseParallelGC,-Xdebug,-Xprof'</span>
</pre></div>
<p>As you can see in the example above, you can pass in multiple options separated by a comma. Multiple options can also be separated by line (just make sure not to use commas):</p>
<div class="codehilite"><pre><span></span>$ ./pants run my-jvm-project:bin --jvm-run-jvm-options<span class="o">=</span><span class="s2">"</span>
<span class="s2">  -XX:+UseParallelGC</span>
<span class="s2">  -Xdebug</span>
<span class="s2">  -Xprof</span>
<span class="s2">  "</span>
</pre></div>
<h2 id="discussion">Discussion</h2>
<p>The pants argument <code>--jvm-run-jvm-options</code> is <em>only</em> used for arguments passed to the JVM itself, not to the executable target. If you need to pass command-line arguments to the executable target, see <a href="cli_args.html">Pass Command-line Arguments to an Executable</a>.</p>
<h2 id="see-also">See Also</h2>
<ul>
<li><a href="cli_args.html">Pass Command-line Arguments to an Executable</a></li>
<li><a href="run.html">Run a Binary Target</a></li>
<li><a href="multiple_jvm_versions.html">Run JVM binaries and tests with different JVM versions</a></li>
</ul>

            <!-- main content end -->

            <div class="generated">
              Generated by <a href="docs.html">publish_docs</a>
              from dist/markdown/html/src/docs/common_tasks/jvm_options.html 2022-12-03T01:08:59.569939
            </div>

          </div> <!-- mainflow -->

        </div> <!-- content -->

      </div>

      <div class="col-md-1">
      </div>

    </div> <!-- row -->
  </div> <!-- container-fluid -->

</div> <!-- page -->

<script src="https://code.jquery.com/jquery-2.2.3.min.js" integrity="sha384-I6F5OKECLVtK/BL+8iSLDEHowSAfUo76ZL9+kGAgTRdiByINKJaqTPH/QVNS1VDb" crossorigin="anonymous"></script>
<script src="bootstrap-custom.min.js"></script>
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
        (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-78111411-1', 'auto');
  ga('send', 'pageview');
</script>
</body>
</html>