GH-129382: change venv's API symlinks default to match the CLI

FFY00 · FFY00 · commit 5017d1b2371d · 2025-01-31T02:27:57.000Z
Signed-off-by: Filipe Laíns &lt;lains@riseup.net&gt;
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
@@ -61,6 +61,8 @@ See :pep:`405` for more background on Python virtual environments.
 
 .. include:: ../includes/wasm-mobile-notavail.rst
 
+.. _venv-cli:
+
 Creating virtual environments
 -----------------------------
 
@@ -298,7 +300,8 @@ creation according to their needs, the :class:`EnvBuilder` class.
       any existing target directory, before creating the environment.
 
     * *symlinks* -- a boolean value indicating whether to attempt to symlink the
-      Python binary rather than copying.
+      Python binary rather than copying (defaults to ``False`` on Windows, and
+      to ``True`` on all other platforms).
 
     * *upgrade* -- a boolean value which, if true, will upgrade an existing
       environment with the running Python - for use when that Python has been
@@ -333,6 +336,11 @@ creation according to their needs, the :class:`EnvBuilder` class.
     .. versionchanged:: 3.13
        Added the ``scm_ignore_files`` parameter
 
+      .. versionchanged:: 3.14
+       The ``symlinks`` parameter's default value was changed from always
+       ``False`` to being platform dependent — ``False`` on Windows, ``True`` on
+       all other platforms — matching the :ref:`CLI <venv-cli>`.
+
     :class:`EnvBuilder` may be used as a base class.
 
     .. method:: create(env_dir)
diff --git a/Lib/venv/__init__.py b/Lib/venv/__init__.py
@@ -17,6 +17,8 @@
 CORE_VENV_DEPS = ('pip',)
 logger = logging.getLogger(__name__)
 
+_USE_SYMLINKS = os.name != 'nt'
+
 
 class EnvBuilder:
     """
@@ -47,7 +49,7 @@ class EnvBuilder:
     """
 
     def __init__(self, system_site_packages=False, clear=False,
-                 symlinks=False, upgrade=False, with_pip=False, prompt=None,
+                 symlinks=_USE_SYMLINKS, upgrade=False, with_pip=False, prompt=None,
                  upgrade_deps=False, *, scm_ignore_files=frozenset()):
         self.system_site_packages = system_site_packages
         self.clear = clear
@@ -631,17 +633,13 @@ def main(args=None):
                         action='store_true', dest='system_site',
                         help='Give the virtual environment access to the '
                              'system site-packages dir.')
-    if os.name == 'nt':
-        use_symlinks = False
-    else:
-        use_symlinks = True
     group = parser.add_mutually_exclusive_group()
-    group.add_argument('--symlinks', default=use_symlinks,
+    group.add_argument('--symlinks', default=_USE_SYMLINKS,
                        action='store_true', dest='symlinks',
                        help='Try to use symlinks rather than copies, '
                             'when symlinks are not the default for '
                             'the platform.')
-    group.add_argument('--copies', default=not use_symlinks,
+    group.add_argument('--copies', default=not _USE_SYMLINKS,
                        action='store_false', dest='symlinks',
                        help='Try to use copies rather than symlinks, '
                             'even when symlinks are the default for '
diff --git a/Misc/NEWS.d/next/Library/2025-01-31-02-27-53.gh-issue-129382.GI93CM.rst b/Misc/NEWS.d/next/Library/2025-01-31-02-27-53.gh-issue-129382.GI93CM.rst
@@ -0,0 +1,2 @@
+Change :class:`venv.EnvBuilder`'s ``symlinks`` parameter's default to match
+the :ref:`CLI <venv-cli>`.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Change :class:`venv.EnvBuilder`'s ``symlinks`` parameter's default to match
	`2`	+the :ref:`CLI <venv-cli>`.