Skip to content

Commit da39c68

Browse files
authored
Update Python install manager docs (GH-145160)
These updates align with v26.0 that was just released.
1 parent 1dfbde9 commit da39c68

File tree

1 file changed

+41
-8
lines changed

1 file changed

+41
-8
lines changed

Doc/using/windows.rst

Lines changed: 41 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -285,6 +285,12 @@ work.
285285
Passing ``--dry-run`` will generate output and logs, but will not modify any
286286
installs.
287287

288+
Passing ``--refresh`` will update all registrations for installed runtimes. This
289+
will recreate Start menu shortcuts, registry keys, and global aliases (such as
290+
``python3.14.exe`` or for any installed scripts). These are automatically
291+
refreshed on installation of any runtime, but may need to be manually refreshed
292+
after installing packages.
293+
288294
In addition to the above options, the ``--target`` option will extract the
289295
runtime to the specified directory instead of doing a normal install.
290296
This is useful for embedding runtimes into larger applications.
@@ -467,6 +473,14 @@ customization.
467473
- ``PYTHON_MANAGER_SOURCE_URL``
468474
- Override the index feed to obtain new installs from.
469475

476+
* - ``install.enable_entrypoints``
477+
- (none)
478+
- True to generate global commands for installed packages (such as
479+
``pip.exe``). These are defined by the packages themselves.
480+
If set to false, only the Python interpreter has global commands created.
481+
By default, true. You should run ``py install --refresh`` after changing
482+
this setting.
483+
470484
* - ``list.format``
471485
- ``PYTHON_MANAGER_LIST_FORMAT``
472486
- Specify the default format used by the ``py list`` command.
@@ -480,8 +494,8 @@ customization.
480494

481495
* - ``global_dir``
482496
- (none)
483-
- Specify the directory where global commands (such as ``python3.14.exe``)
484-
are stored.
497+
- Specify the directory where global commands (such as ``python3.14.exe``
498+
and ``pip.exe``) are stored.
485499
This directory should be added to your :envvar:`PATH` to make the
486500
commands available from your terminal.
487501

@@ -491,6 +505,7 @@ customization.
491505
This directory is a temporary cache, and can be cleaned up from time to
492506
time.
493507

508+
494509
Dotted names should be nested inside JSON objects, for example, ``list.format``
495510
would be specified as ``{"list": {"format": "table"}}``.
496511

@@ -737,6 +752,14 @@ directory containing the configuration file that specified them.
737752
(e.g. ``"pep514,start"``).
738753
Disabled shortcuts are not reactivated by ``enable_shortcut_kinds``.
739754

755+
* - ``install.hard_link_entrypoints``
756+
- True to use hard links for global shortcuts to save disk space. If false,
757+
each shortcut executable is copied instead. After changing this setting,
758+
you must run ``py install --refresh --force`` to update existing
759+
commands.
760+
By default, true. Disabling this may be necessary for troubleshooting or
761+
systems that have issues with file links.
762+
740763
* - ``pep514_root``
741764
- Registry location to read and write PEP 514 entries into.
742765
By default, :file:`HKEY_CURRENT_USER\\Software\\Python`.
@@ -876,12 +899,22 @@ default).
876899

877900
* -
878901
- The package may be available but missing the generated executable.
879-
We recommend using the ``python -m pip`` command instead,
880-
or alternatively the ``python -m pip install --force pip`` command
881-
will recreate the executables and show you the path to
882-
add to :envvar:`PATH`.
883-
These scripts are separated for each runtime, and so you may need to
884-
add multiple paths.
902+
We recommend using the ``python -m pip`` command instead.
903+
Running ``py install --refresh`` and ensuring that the global shortcuts
904+
directory is on :envvar:`PATH` (it will be shown in the command output if
905+
it is not) should make commands such as ``pip`` (and other installed
906+
packages) available.
907+
908+
* - I installed a package with ``pip`` but its command is not found.
909+
- Have you activated a virtual environment?
910+
Run the ``.venv\Scripts\activate`` script in your terminal to activate.
911+
912+
* -
913+
- New packages do not automatically have global shortcuts created by the
914+
Python install manager. Similarly, uninstalled packages do not have their
915+
shortcuts removed.
916+
Run ``py install --refresh`` to update the global shortcuts for newly
917+
installed packages.
885918

886919
* - Typing ``script-name.py`` in the terminal opens in a new window.
887920
- This is a known limitation of the operating system. Either specify ``py``

0 commit comments

Comments
 (0)