Skip to content

Commit 6dc03ef

Browse files
[3.14] Update Python install manager docs (GH-145160)
These updates align with v26.0 that was just released. (cherry picked from commit da39c68) Co-authored-by: Steve Dower <steve.dower@python.org>
1 parent 9d53cbf commit 6dc03ef

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
@@ -287,6 +287,12 @@ work.
287287
Passing ``--dry-run`` will generate output and logs, but will not modify any
288288
installs.
289289

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

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

483497
* - ``global_dir``
484498
- (none)
485-
- Specify the directory where global commands (such as ``python3.14.exe``)
486-
are stored.
499+
- Specify the directory where global commands (such as ``python3.14.exe``
500+
and ``pip.exe``) are stored.
487501
This directory should be added to your :envvar:`PATH` to make the
488502
commands available from your terminal.
489503

@@ -493,6 +507,7 @@ customization.
493507
This directory is a temporary cache, and can be cleaned up from time to
494508
time.
495509

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

@@ -739,6 +754,14 @@ directory containing the configuration file that specified them.
739754
(e.g. ``"pep514,start"``).
740755
Disabled shortcuts are not reactivated by ``enable_shortcut_kinds``.
741756

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

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

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

0 commit comments

Comments
 (0)