Nav2: the repository is an index, and the stack lives in thirty-seven packages
ROS 2 Navigation Framework and System
At a glance
- What is it?
- Nav2 is the ROS 2 navigation framework, and its repository reads as a documentation table of contents rather than an introduction: concepts, setup, configuration, plugin and API documentation all live on a separate site. What the repository does hold is the package layout, the per-distribution build matrix, and a container build driven by mixin variables.
- Who is it for?
- Nav2 fits a robotics team already on ROS 2 that needs a navigation stack with swappable controllers, planners and costmaps rather than a monolith, and that can read plugin documentation and API references on a hosted site. It does not fit a team that wants to configure navigation from files in one repository, since the configuration guide is external, and it does not fit anyone who needs a single documented licence from the repository metadata, which does not identify one.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- ros-navigation/navigation25,058 ★ · +318
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| ros-navigation/navigation2 | 4.7k | 5.1k |
318 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The top level file is a table of links, not an explanation
Almost nothing about the software is described in the repository's own readme. What it does is enumerate where the documentation lives: concepts and getting started, a first time setup guide, ROS distribution statuses, a build and install guide that also covers Docker containers, general tutorials, algorithm developer tutorials, a configuration guide, a page of navigation plugins, API documentation on its own host, a set of ROSCon talks with citations, migration guides, and a contribution page. There is no architecture summary, no list of what the stack does, and no example configuration. That is a deliberate division of labour, and it has a practical cost: evaluating Nav2 means reading another site, and the repository gives you no way to tell from its contents which parts of the stack you would actually be adopting.
The package list is the architecture
What the repository does show is the shape of the system, because each concern is its own directory. Localisation is nav2_amcl, the costmap layer is nav2_costmap_2d, the recovery and behaviour logic sits in nav2_behaviors, and nav2_bt_navigator with nav2_behavior_tree handles decision making. Controllers are split into separate packages, with nav2_dwb_controller, nav2_mppi_controller, nav2_graceful_controller and nav2_rotation_shim_controller all present, and planners are split the same way across nav2_navfn_planner, nav2_smac_planner and nav2_theta_star_planner. Smoothing, velocity smoothing and collision monitoring are their own packages too. Newer entries include nav2_route, nav2_docking, nav2_following, nav2_waypoint_follower and a nav2_loopback_sim. The consequence is that choosing a navigation stack in ROS 2 is largely a question of which controller and planner packages you compose.
Build status is tracked per distribution, and there are three
The build matrix is the most informative table in the file, because it names the packages and the targets together. Every package is checked twice per distribution, once as a source build and once as a Debian binary, against build.ros2.org, and three distributions are covered: humble on Ubuntu jammy, jazzy on noble, and lyrical on resolute. That last one is the signal worth reading carefully, since it means the project is tracking a distribution most users have not run yet. The release list tells a second story, with 1.3.14 and 1.5.3 from 2026-10-17 and 1.5.2 from 2026-09-16, so more than one line is being patched. The file does not say which release belongs to which distribution, which means choosing a version is a question for the documentation rather than for the readme.
The container build needs mixins and the repository root
There is a Dockerfile, and it is configured entirely through build arguments. Two constraints are stated in its own comments. The build context must be the /navigation2 root folder, because the file copies from there, and the mixins are exported before the build:
export UNDERLAY_MIXINS="debug ccache lld"
export OVERLAY_MIXINS="debug ccache coverage-gcc lld"
docker build -t nav2:latest \
--build-arg UNDERLAY_MIXINS \
--build-arg OVERLAY_MIXINS ./The base image defaults to ros:rolling, so a container build tracks the rolling distribution unless you pass a different FROM_IMAGE. One stage, the cacher, exists for caching: it imports the underlay workspace from tools/underlay.repos with vcs import and copies package manifests and COLCON_IGNORE markers so that a source change does not invalidate the dependency layer. The build stage installs ccache, lcov, lld and python3-pip, plus four different ROS middleware implementations, which tells you the image is set up to test the stack across RMW vendors rather than one.
There is a Semgrep ruleset in the repository root
The supporting tooling is more visible than usual. Alongside the packages sit a .devcontainer directory and a .vscode directory, so both a container and a local editor setup are provided, plus a .circleci directory and GitHub workflows referenced by the badges at the top of the file. Static analysis is configured rather than assumed: a .semgrep.yml ruleset with a matching .semgrepignore, and a .pre-commit-config.yaml for hooks that run before a commit lands. Coverage is tracked through codecov.yml, and documentation generation is set up with a Doxyfile and a doc directory. For a contributor, that means the checks a change has to pass are visible in the repository, which is the opposite of the documentation situation where the user-facing material is hosted elsewhere.
Community support and paid support have separate addresses
Two channels are offered and they are not the same thing. Community questions go to a Slack workspace, and the file includes a practical warning about the invite link: if it does not work, contact maintainers to reactivate it, which is an admission that invite links expire. Professional services go to Open Navigation, with a contact address given in the file, and the sponsors section states that Open Navigation LLC provides project leadership, maintenance, development and support services to the Nav2 and ROS community, described as the reason the project can continue to be professionally maintained. Around it sit sponsors with stated roles: Dexory on warehouse digital twins, Nvidia on GPU and AI hardware, AMD on embedded compute, Polymath Robotics on safety-critical industrial navigation, Stereolabs on ZED stereo cameras, 3Laws Robotics on collision avoidance, and Staer on autonomous mobile robots.
The licence is not identified in the repository metadata
One gap is worth naming before anyone builds on this. A LICENSE file is present at the repository root, but the licence shown in the repository metadata is recorded as unasserted, meaning no identifier was detected. That is not a licence problem in itself. It does mean that any automated check reading package metadata sees nothing, so a downstream tool that gates on licence identifiers will not find one here. The other gap is documentation-shaped rather than legal: the file is explicit that everything about configuring the stack is in the configuration guide on the hosted site, so the repository is not a place where you can read what a controller parameter does.
Editorial conclusion
Nav2 fits a robotics team already on ROS 2 that needs a navigation stack with swappable controllers, planners and costmaps rather than a monolith, and that can read plugin documentation and API references on a hosted site. It does not fit a team that wants to configure navigation from files in one repository, since the configuration guide is external, and it does not fit anyone who needs a single documented licence from the repository metadata, which does not identify one. Before you adopt it, check four things: which ROS distribution you are on and therefore which build matrix column applies to you, which controller and planner packages you intend to swap between, whether you can run the container build from the repository root with the mixin variables set, and where your configuration will live once the stack is running.
Frequently asked questions
How do I install Nav2?
The file routes installation to its own documentation rather than giving commands: a build and install guide in the development guides, a Docker containers package, and a first time setup guide. For containers it does show the shape of the build, with the context required to be the navigation2 root folder and UNDERLAY_MIXINS and OVERLAY_MIXINS passed as build arguments to a base image that defaults to ros:rolling.
What is Navigation 2?
Nav2 is the ROS 2 navigation framework and system, described in the repository as such. The repository itself is a set of packages named nav2_, covering localisation, costmaps, behaviours, a behaviour tree navigator, several controllers and planners, smoothing, collision monitoring and a bringup package, with the explanatory documentation hosted on docs.nav2.org and API references on api.nav2.org.
Where can I find documentation for ROS 2 navigation?
On docs.nav2.org, which the file indexes into concepts and getting started, a first time setup guide, ROS distribution statuses, build and install, general and algorithm developer tutorials, a configuration guide, navigation plugins, ROSCon talks and citations, and migration guides. API documentation lives separately on api.nav2.org, and the repository root carries a Doxyfile and a doc directory.
What is the difference between Navigation 2 and Navigation 3?
The file describes no Navigation 3. What changes between versions in this repository is the ROS distribution rather than a product number: build status is tracked for humble on jammy, jazzy on noble and lyrical on resolute, with source and Debian jobs for each package, and migration guides are published for version transitions.
Does NASA use ROS?
The file says nothing about NASA. The organisations it names are Open Navigation, which provides project leadership, maintenance, development and support services, and the sponsors Dexory, Nvidia, AMD, Polymath Robotics, Stereolabs, 3Laws Robotics and Staer, each described by the kind of robotics work it does.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/ros-navigation-navigation2)Star history chart for your README
[](https://hysenlabs.com/projects/ros-navigation-navigation2)Was this useful?