Skip to content

New windows binary install instructions #6070

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
knmcguire wants to merge 11 commits into
base: rolling
Choose a base branch
from
Open

New windows binary install instructions #6070

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
035d8f2
revert install location rolling
knmcguire Dec 5, 2025
561a371
do everything in cmd prompt now
knmcguire Dec 5, 2025
c5b1b92
remove powershell from dev instructions too
knmcguire Dec 5, 2025
79715d5
add installation script
knmcguire Dec 5, 2025
7f5173a
change pixi_ws/ros2-windows to /dev/distro
knmcguire Dec 5, 2025
c9a7005
consistency command prompt
knmcguire Dec 5, 2025
d9fde87
command prompt consistency
knmcguire Dec 5, 2025
0dc0593
fix typo
knmcguire Dec 5, 2025
a64a706
fix whitespace and codeblock issues ci
knmcguire Dec 5, 2025
c754417
Merge branch 'rolling' into new-win-bin-install
knmcguire Dec 16, 2025
5689462
Merge branch 'rolling' into new-win-bin-install
mjcarroll Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 24 additions & 20 deletions source/Installation/Alternatives/Windows-Development-Setup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,26 +27,26 @@ Create a location for the ROS 2 installation

This location will contain both the installed binary packages, plus the ROS 2 installation itself.

Start a powershell session (usually by clicking on the start menu, then typing ``powershell``).
Start a Command Prompt session (usually by clicking on the start menu, then typing ``command prompt``).

Then create a directory to store the installation.
Because of Windows path-length limitations, this should be as short as possible.
We'll use ``C:\dev`` for the rest of these instructions.

.. code-block:: console

$ md C:\dev
$ mkdir C:\dev

Increase the Windows maximum path length
----------------------------------------

By default, Windows is restricted to a maximum path length (MAX_PATH) of 260 characters.
The ROS 2 build will use significantly longer path lengths, so we will increase that.
Using the powershell session you started above, run the following:
Using the session you started above, run the following:

.. code-block:: console

$ New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
$ powershell New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

You can read more about this limitation in `Microsoft's documentation <https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry>`__.

Expand All @@ -60,11 +60,11 @@ Install MSVC
In order to compile the ROS 2 code, the MSVC compiler must be installed.
Currently it is recommended to use MSVC 2019.

Continue using the previous powershell session, and run the following command to download it:
Continue using the previous session, and run the following command to download it:

.. code-block:: console

$ irm https://aka.ms/vs/16/release/vs_buildtools.exe -OutFile vs_buildtools_2019.exe
$ powershell irm https://aka.ms/vs/16/release/vs_buildtools.exe -OutFile vs_buildtools_2019.exe

Now install MSVC 2019:

Expand All @@ -81,36 +81,40 @@ Install pixi

ROS 2 uses `conda-forge <https://conda-forge.org/>`__ as a backend for packages, with `pixi <https://pixi.sh/latest/>`__ as the frontend.

Continue using the previous powershell session, and use the instructions from https://pixi.sh/latest/ to install ``pixi``.
Once ``pixi`` has been installed, close the powershell session and start it again, which will ensure ``pixi`` is on the PATH.
.. note::

The installation of conda-forge may trigger Windows Defender to treat it as a threat, but this can be safely ignored by clicking "More info" and "Run anyway".

Use use the instructions on https://pixi.sh/latest/ to install ``pixi`` either with the Windows Installer or using command line in your opened Command Prompt terminal.

Once ``pixi`` has been installed, close the Command Prompt session and start it again, which will ensure ``pixi`` is on the PATH.

Install dependencies
^^^^^^^^^^^^^^^^^^^^

Download the pixi configuration file in the existing powershell session:
Download the pixi configuration file in the existing Command Prompt session:

.. code-block:: console

$ cd C:\dev
$ irm https://raw.githubusercontent.com/ros2/ros2/refs/heads/{REPOS_FILE_BRANCH}/pixi.toml -OutFile pixi.toml
$ powershell irm https://raw.githubusercontent.com/ros2/ros2/refs/heads/{REPOS_FILE_BRANCH}/pixi.toml -OutFile pixi.toml

Install dependencies:

.. code-block:: console

$ pixi install

You should now close the powershell session, as the rest of the instructions will use the Windows command prompt.

Build ROS 2
-----------

Start a new Windows command prompt, which will be used for the build.
You can use the same Windows Command Prompt for the build.

Source the MSVC compiler
^^^^^^^^^^^^^^^^^^^^^^^^

This is required in the command prompt you'll use to compile ROS 2, but it is *not* required when running:
This is required in the Command Prompt you'll use to compile ROS 2, but it is *not* required when running:

.. code-block:: console

Expand All @@ -119,7 +123,7 @@ This is required in the command prompt you'll use to compile ROS 2, but it is *n
Source the pixi environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This is required in every command prompt you open to set up paths to the dependencies:
This is required in every Command Prompt you open to set up paths to the dependencies:

.. code-block:: console

Expand Down Expand Up @@ -173,12 +177,12 @@ To build the ``\{DISTRO}`` folder tree:
Setup environment
-----------------

Start a new Windows command prompt, which will be used in the examples.
Start a new Windows Command Prompt, which will be used in the examples.

Source the pixi environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This is required in every command prompt you open to set up paths to the dependencies:
This is required in every Command Prompt you open to set up paths to the dependencies:

.. code-block:: console

Expand All @@ -188,7 +192,7 @@ This is required in every command prompt you open to set up paths to the depende
Source the ROS 2 environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This is required in every command prompt you open to setup the ROS 2 workspace:
This is required in every Command Prompt you open to setup the ROS 2 workspace:

.. code-block:: console

Expand Down Expand Up @@ -219,15 +223,15 @@ Afterwards you can get a summary of the tests using this command:

$ colcon test-result

To run the examples, first open a clean new ``cmd.exe`` and set up the workspace by sourcing the ``local_setup.bat`` file.
To run the examples, first open a clean new Command Prompt and set up the workspace by sourcing the ``local_setup.bat`` file.
Then, run a C++ ``talker``\ :

.. code-block:: console

$ call install\local_setup.bat
$ ros2 run demo_nodes_cpp talker

In a separate command prompt you can do the same, but instead run a Python ``listener``\ :
In a separate Command Prompt you can do the same, but instead run a Python ``listener``\ :

.. code-block:: console

Expand All @@ -240,7 +244,7 @@ Hooray!

.. note::

It is not recommended to build in the same cmd prompt that you've sourced the ``local_setup.bat``.
It is not recommended to build in the same Command Prompt that you've sourced the ``local_setup.bat``.

Next steps
----------
Expand Down
65 changes: 32 additions & 33 deletions source/Installation/Windows-Install-Binary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,20 +25,15 @@ Create a location for the ROS 2 installation

This location will contain both the installed binary packages, plus the ROS 2 installation itself.

Start a powershell session (usually by clicking on the start menu, then typing ``powershell``).
Start a Command Prompt session (usually by clicking on the start menu, then typing ``Command Prompt``).

Then create a directory to store the installation.
Because of Windows path-length limitations, this should be as short as possible.
We'll use ``C:\pixi_ws`` for the rest of these instructions.
We'll use ``C:\dev`` for the rest of these instructions.

.. code-block:: console

$ md C:\pixi_ws

.. note::

Note: the ROS 2 binary packages are currently not relocatable, which is being tracked in a `documentation issue <https://github.com/ros2/ros2_documentation/issues/5384>`__.
Please use ``C:\pixi_ws`` in the interim.
$ md C:\dev

Install prerequisites
---------------------
Expand All @@ -52,36 +47,41 @@ ROS 2 uses `conda-forge <https://conda-forge.org/>`__ as a backend for packages,
Install pixi
^^^^^^^^^^^^

Continue using the previous powershell session, and use the instructions on https://pixi.sh/latest/ to install ``pixi``.
Once ``pixi`` has been installed, close the powershell session and start it again, which will ensure ``pixi`` is on the PATH.
Use use the instructions on https://pixi.sh/latest/ to install ``pixi`` either with the Windows Installer or using command line in your opened Command Prompt terminal.

Install dependencies
^^^^^^^^^^^^^^^^^^^^
Once ``pixi`` has been installed, close the Command Prompt session and start it again, which will ensure ``pixi`` is on the PATH.

Download the pixi configuration file in the existing powershell session:

.. code-block:: console
Install ROS 2
-------------

Binary releases of {DISTRO_TITLE_FULL} are not provided.
Instead you may download nightly :ref:`prerelease binaries <Prerelease_binaries>`.

$ cd C:\pixi_ws
$ irm https://raw.githubusercontent.com/ros2/ros2/refs/heads/{REPOS_FILE_BRANCH}/pixi.toml -OutFile pixi.toml
* Download the latest package for Windows, e.g., ``ros2-package-windows-AMD64.zip``.
* Unpack the zip file somewhere on your system (we'll assume ``C:\dev\``).
* Change the name of the extracted folder to match the distro (we'll assume ``C:\dev\{DISTRO}``)

Install dependencies:

Install Pixi dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^

Go to the folder where you unzipped the ROS 2 prereleased binaries and install the dependencies

.. code-block:: console

$ cd C:\dev\{DISTRO}
$ pixi install

Install ROS 2
-------------
Run preinstall installation script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Go to the releases page: https://github.com/ros2/ros2/releases
* Download the latest package for Windows, e.g., ``ros2-{DISTRO}-*-windows-release-amd64.zip``.
Run the preinstall installation setup script to make sure that the zipped file are able to run in the current folder the ROS 2 binaries have been exctrated to:

.. note::
.. code-block:: console

There may be more than one binary download option which might cause the file name to differ.
$ pixi run python preinstall_setup_windows.py
Copy link
Member

@mjcarroll mjcarroll Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not important for getting this in, but should we consider making this a `pixi task: https://pixi.sh/latest/workspace/advanced_tasks/

Copy link
Contributor Author

@knmcguire knmcguire Dec 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yes absolutely, but that would require a PR to https://github.com/ros2/ros2, and this one is based on a PR in https://github.com/ros2/ci that just got merged after a half a year.

Also an alternative, is to also present an self-extracting archive with some automated post-extract command lines... still experimenting with that but that would be pretty close to an actual install and would further reduce the instructions. But that is still ongoing and perhaps would be to discuss this in an separate ticket perhaps.


* Unpack the zip file somewhere (we'll assume ``C:\pixi_ws\ros2-windows``).

Install additional RMW implementations (optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -93,7 +93,7 @@ See the :doc:`guide <../How-To-Guides/Working-with-multiple-RMW-implementations>
Setup environment
-----------------

Start a new Windows command prompt, which will be used in the examples.
In either the same Command Prompt terminal or a new one, you can source the ROS 2 environment

Source the pixi environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -102,36 +102,35 @@ Source the pixi environment to set up dependencies:

.. code-block:: console

$ cd C:\pixi_ws
$ pixi shell
$ cd C:\dev\{DISTRO}

Source the ROS 2 environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This is required in every command prompt you open to setup the ROS 2 workspace:
This is required in every Command Prompt you open to setup the ROS 2 workspace:

.. code-block:: console

$ call C:\pixi_ws\ros2-windows\local_setup.bat
$ call C:\dev\{DISTRO}\local_setup.bat

If you do not have RTI Connext DDS installed on your computer, it is normal to receive a warning that it is missing.

Try some examples
-----------------

In a command prompt, set up the ROS 2 environment as described above and then run a C++ ``talker``\ :
In a Command Prompt, set up the ROS 2 environment as described above and then run a C++ ``talker``\ :

.. code-block:: console

$ ros2 run demo_nodes_cpp talker

Start another command shell and run a Python ``listener``\ :
Start another Command Prompt terminal and run a Python ``listener``\ :

.. code-block:: console

$ ros2 run demo_nodes_py listener

You should see the ``talker`` saying that it's ``Publishing`` messages and the ``listener`` saying ``I heard`` those messages.
You should see the ``talker`` saying that it is ``Publishing`` messages and the ``listener`` saying ``I heard`` those messages.
This verifies both the C++ and Python APIs are working properly.
Hooray!

Expand All @@ -156,4 +155,4 @@ Uninstall

.. code-block:: console

$ rmdir /s /q C:\pixi_ws
$ rmdir /s /q C:\dev\{DISTRO}