Skip to content

Commit 6a22963

Browse files
authored
Improve the administrative install docs for Python Install Manager (pythonGH-134066)
1 parent 20095fb commit 6a22963

File tree

1 file changed

+38
-8
lines changed

1 file changed

+38
-8
lines changed

Doc/using/windows.rst

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -98,8 +98,9 @@ does not affect any installs of Python runtimes. Uninstalling the Python install
9898
manager does not uninstall any Python runtimes.
9999

100100
If you are not able to install an MSIX in your context, for example, you are
101-
using automated deployment software that does not support it, please see
102-
:ref:`pymanager-advancedinstall` below for more information.
101+
using automated deployment software that does not support it, or are targeting
102+
Windows Server 2019, please see :ref:`pymanager-advancedinstall` below for more
103+
information.
103104

104105

105106
Basic Use
@@ -515,6 +516,11 @@ per-machine installs to its default location in Program Files. It will attempt
515516
to modify the system :envvar:`PATH` environment variable to include this install
516517
location, but be sure to validate this on your configuration.
517518

519+
.. note::
520+
521+
Windows Server 2019 is the only version of Windows that CPython supports that
522+
does not support MSIX. For Windows Server 2019, you should use the MSI.
523+
518524
Be aware that the MSI package does not bundle any runtimes, and so is not
519525
suitable for installs into offline environments without also creating an offline
520526
install index. See :ref:`pymanager-offline` and :ref:`pymanager-admin-config`
@@ -535,13 +541,32 @@ depending on whether it was installed from python.org or through the Windows
535541
Store. Attempting to run the executable directly from Program Files is not
536542
recommended.
537543

538-
To programmatically install or uninstall the MSIX without using your
539-
distribution platform's native support, the `Add-AppxPackage
540-
<https://learn.microsoft.com/powershell/module/appx/add-appxpackage>`_ and
541-
`Remove-AppxPackage <https://learn.microsoft.com/powershell/module/appx/remove-appxpackage>`_
542-
PowerShell cmdlets are simplest to use:
544+
To programmatically install the Python install manager, it is easiest to use
545+
WinGet, which is included with all supported versions of Windows:
543546

544-
.. code::
547+
.. code-block:: powershell
548+
549+
$> winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity
550+
551+
# Optionally run the configuration checker and accept all changes
552+
$> py install --configure -y
553+
554+
To download the Python install manager and install on another machine, the
555+
following WinGet command will download the required files from the Store to your
556+
Downloads directory (add ``-d <location>`` to customize the output location).
557+
This also generates a YAML file that appears to be unnecessary, as the
558+
downloaded MSIX can be installed by launching or using the commands below.
559+
560+
.. code-block:: powershell
561+
562+
$> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --disable-interactivity
563+
564+
To programmatically install or uninstall an MSIX using only PowerShell, the
565+
`Add-AppxPackage <https://learn.microsoft.com/powershell/module/appx/add-appxpackage>`_
566+
and `Remove-AppxPackage <https://learn.microsoft.com/powershell/module/appx/remove-appxpackage>`_
567+
PowerShell cmdlets are recommended:
568+
569+
.. code-block:: powershell
545570
546571
$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
547572
...
@@ -555,6 +580,11 @@ to install the Python install manager for all users from the MSIX package. Users
555580
will still need to install their own copies of Python itself, as there is no way
556581
to trigger those installs without being a logged in user.
557582

583+
Note that the MSIX downloadable from the Store and from the Python website are
584+
subtly different and cannot be installed at the same time. Wherever possible,
585+
we suggest using the above commands to download the package from the Store to
586+
reduce the risk of setting up conflicting installs.
587+
558588
.. _pymanager-admin-config:
559589

560590
Administrative Configuration

0 commit comments

Comments
 (0)