Installation on Windows
=======================

Installation Options
~~~~~~~~~~~~~~~~~~~~

.. note::

   While administrator privileges/sudo may be necessary to install portmod's dependencies, you should not run portmod with administrator privileges. It is designed to be run as a user program.

Chocolatey
----------
`Chocolatey <https://chocolatey.org/install>`_ can optionally be used to install the dependencies. This must be done in a prompt with administrator privileges.

.. code:: powershell

   choco install git python310 sandboxie

This should add most of the tools to your ``PATH`` automatically. It will
not add the sandboxie directory to your ``PATH``, so that must be done manually.

Portmod can then be installed with pip. Note that this can be done as a regular user if you add the flag ``--user`` at the end.

.. code:: powershell

   pip3 install portmod --upgrade

WSL2
----

Portmod also works in WSL2 (WSL1 is incompatible). As there are many different linux distros available for WSL2, we cannot provide an example for every WSL2 image here.

Some WSL2 setup may be required. See https://learn.microsoft.com/en-us/windows/wsl/install.

E.g. Using Ubuntu WSL:

.. code:: bash

   sudo apt-get install git python3 bubblewrap


Portmod can then be installed with pip. Note that this can be done as a regular user if you add the flag ``--user`` at the end.

.. code:: bash

   pip3 install portmod --upgrade


Installing Manually
~~~~~~~~~~~~~~~~~~~

In addition to the dependencies specified in
:ref:`installation`, noting that the python dependencies can
be installed with pip, which comes with Python, you will likely need to install
several other dependencies, or make some changes to get previously mentioned
dependencies to work.

Python
------

https://www.python.org/downloads/windows/

If installing manually, python provides an option to add it to your
``PATH`` environment variable during installation, which you should
select (otherwise, you must add the python scripts directory to your
``PATH`` manually).

Git
---

https://git-scm.com/download/win

While a dependency for all systems, it generally is not already
installed on Windows.

When installing manually, Git will add the necessary directory to your
``PATH`` by default (the “recommended” option), and as long as you do
not choose the “Use Git from Git Bash Only” option when installing,
Portmod will be able to find your Git installation automatically.

7-zip
-----

.. note::

   7-zip is not generally needed any more since Pybuild1 is deprecated.
   Some of the repositories which haven't been updated in a while may still
   rely on it.

https://www.7-zip.org/

7-zip is optional, and can be replaced with other archive tools which
are supported by patool (unfortunately, no nicely formatted list exists,
but see `the
repo <https://github.com/wummel/patool/tree/master/patoolib/programs>`__
for supported programs).

7-zip is recommended as it covers most archive types not supported
natively by patool, including the commonly encountered types (see note
on patool in dependencies section on the :ref:`installation` page).

The 7-zip program files directory needs to be added to your ``PATH``
environment variable so that it can be detected by patool.

Sandboxie
---------

https://github.com/sandboxie-plus/Sandboxie/releases

Either the classic or the "plus" version can be used.
Note that the "plus" version contains non-Free components.

Sandboxie is the Sandbox tool Portmod interfaces with on Windows
(see :ref:`sandbox`).
Note that Portmod automatically configures Sandboxie; you do not
need to, and indeed should not, modify the sandbox configurations
generated by Portmod.

The sandboxie program files directory needs to be added to your ``PATH``
environment variable so that it can be detected by portmod.

PySAT
-----
(known on pypi as python-sat)

The PySAT wheels distributed on pypi require Microsoft Visual C++
Redistributable, which if you don’t already have, can be found at the
following location:

https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads

Setup information
-----------------

It is worth noting that, while Portmod in general does not require
administrator privileges, you may need administrator privileges to
create symlinks on certain versions of Windows (newer versions of
Windows 10 should support creating symlinks without privileges, though
it may be necessary to enable a developer feature for this).
Currently the only symlink portmod requires is the profile symlink, so
when you select a profile using
``portmod <prefix> select profile set``, you might need to ensure that
``portmod`` is run with administrator privileges.
