Mohamed Hamed

Posted on Oct 8

Frappe / ERPNext v16.50: The Future of Desktop Icons and Desk Navigation

#frappe #erpnext

What “retiring” really means, what changed in v16.50, and how custom apps should prepare

By Mohamed Hamed (@m7amedenho)

Published: October 2026

Frappe Framework and ERPNext v16.50 introduce a clearer navigation model for the Desk. The official hierarchy is now:

App
└── Module
    └── Sidebar
        ├── DocTypes
        ├── Reports
        ├── Pages
        ├── Workspaces
        └── Dashboards

This change raises an important question for developers and implementers who already use the Desktop Icon grid:

Is Desktop Icon being removed, and should custom apps stop using it immediately?

The short answer is:

The old Desktop Icon grid still works as a compatibility fallback for upgraded sites, but it is retiring. New development should target the Apps screen, Dock, module sidebars, and the new navigation hierarchy.

That distinction matters. “Retiring” does not mean “deleted in v16.50,” and it does not mean that every Desktop Icon-related mechanism suddenly stopped working.

1. What v16.50 actually changed

Frappe describes v16.50 as a polished v16 rather than v17. The release focuses heavily on navigation and user experience while attempting to minimize breaking changes.

The redesigned Desk has a much clearer information hierarchy:

Apps screen
    ↓
Application
    ↓
Dock of modules
    ↓
One sidebar per module
    ↓
DocTypes, reports, pages, workspaces, and dashboards

The Desktop page now focuses on applications. After a user opens an app, its modules appear in the Dock. Opening a module provides the sidebar associated with that module.

This is more than a visual redesign. It changes how navigation should be modeled in a large Frappe application.

The official v16.50 announcement describes the hierarchy as:

App → Module → DocTypes, Reports, Pages, Workspaces, Dashboards, and everything else.

See the official v16.50 announcement.

2. What happens to an existing Desktop Icon grid?

An upgrade does not immediately delete an existing site's Desktop Icons or their arrangement.

According to Frappe's migration documentation:

A site already using the Desktop Icon grid keeps using it after the upgrade.
Its icons and their arrangement are retained.
The grid remains available as a fallback while the site moves to the Apps screen.
New sites start on the Apps screen rather than the old grid.
The grid will be removed in a future release after most sites have migrated.

In other words:

Existing upgraded site
        ↓
Desktop Icon grid remains available
        ↓
Temporary compatibility fallback
        ↓
Migration to Apps screen
        ↓
Future removal of the old grid

The documentation does not currently promise a specific removal version. It would therefore be inaccurate to claim that the grid will definitely disappear in v17, or in any other named release, until Frappe announces that explicitly.

See Migrating a Version 16 site to the new Desk navigation.

3. Desktop Icon, Desktop grid, and Apps screen are not the same thing

Some of the confusion comes from using “Desktop Icon” to describe several related concepts.

The Desktop Icon grid

This is the old home-screen experience containing a grid of icons. It is the part that the official documentation describes as a retiring fallback.

Desktop Icon records

These are records used by the legacy grid and by migration or compatibility behavior. Their continued presence is not, by itself, evidence that the old grid remains the recommended architecture.

The Apps screen

This is the forward-looking Desktop experience. It shows one entry per application and leads the user into that app's modules, Dock, and sidebars.

Therefore, seeing a Desktop Icon DocType or related code in the framework should not be interpreted as a recommendation to base new application navigation on the old grid.

It exists because Frappe must support real installations while they migrate.

4. Why would Frappe maintain something that is retiring?

Deprecation and maintenance can happen at the same time.

ERP installations cannot safely switch navigation models overnight. Existing sites may contain:

custom Desktop Icons;
user-specific icon arrangements;
public and private Workspaces;
custom Workspace Sidebars;
role-dependent shortcuts;
bookmarks and direct links;
multiple custom apps with their own navigation conventions.

Frappe therefore needs to preserve the old experience long enough for administrators and developers to migrate safely. Fixing bugs in that compatibility layer does not contradict its future removal.

It means the project is supporting the transition instead of breaking upgraded sites immediately.

5. Reading the GitHub issues correctly

The GitHub issue history contains reports involving Desktop Icons, Workspaces, layout persistence, permissions, caching, and Workspace Sidebars. These reports need chronological context.

They should not all be presented as evidence that Desktop Icons are currently broken. Some issues were reported during active v16 development and later fixed or released. For example, the Desktop Icon caching issue #36325 was closed and its fix was released in v16.7.0.

At the same time, it would also be inaccurate to claim that every Desktop Icon issue has been resolved. At the time of writing, reports such as creating an icon from the Desktop Icon list #36953 and the broader layout and shortcut report #38292 remain open.

The responsible interpretation is:

The issue history documents an active transition and stabilization process. It contains both completed fixes and unresolved edge cases.

When evaluating an issue, check:

When it was opened.
Which branch and version it affects.
Whether it is open or closed.
Whether a pull request was merged.
Whether the fix has a released version.
Whether the behavior still reproduces on the version you deploy.

This is more useful than treating every historical issue as a current production defect.

6. What should custom app developers use now?

For a new custom app, start with the Apps screen and the new navigation structure.

Declare the application in hooks.py using add_to_apps_screen:

add_to_apps_screen = [
    {
        "name": "my_app",
        "logo": "/assets/my_app/images/logo.svg",
        "title": "My App",
        "route": "/desk/my-module",
        "has_permission": "my_app.utils.check_app_permission",
        "sequence_id": 50,
    }
]

The fields have distinct responsibilities:

Field	Purpose
`name`	The internal app name
`logo`	The icon used on the Apps screen and app Dock
`title`	The label shown to the user
`route`	The destination opened from the app icon
`has_permission`	Optional function controlling access to the app
`sequence_id`	Optional ordering value; lower values appear first

After registering the app, organize its navigation around:

Custom App
├── Module A
│   ├── Module Sidebar
│   ├── Workspaces
│   ├── DocTypes
│   └── Reports
└── Module B
    ├── Module Sidebar
    ├── Pages
    └── Dashboards

The official developer example is available in The desktop and Apps screen.

Do not treat add_to_apps_screen as the entire navigation architecture. It places the application on the Apps screen; the Dock and module sidebars provide the structure inside the application.

7. A practical migration plan for an existing site

The safest strategy is not to delete old icons manually. It is to audit, migrate, test, and then switch.

Step 1: Take a complete backup

Back up the database, public files, private files, site configuration, and the exact revisions of all installed apps. A database backup alone is not a complete rollback plan.

Step 2: Rehearse on staging

Restore production data into an isolated staging environment and run the upgrade there first. Navigation is permission-sensitive, so a successful Administrator test is not enough.

Step 3: Inventory current navigation

Record:

Desktop Icons and their routes;
customized icon arrangements;
public and private Workspaces;
customized Workspace Sidebars;
role-specific links;
custom Pages and Reports;
custom apps that still ship an older sidebar format.

Screenshots are useful here because they make post-migration comparison much faster.

Step 4: Review migration output

Note any modules that were merged, Workspaces placed under Custom Workspaces, and apps still using an older sidebar format.

Step 5: Assign every Workspace to the correct module

In the new structure, a Workspace belongs to a module because that module determines where the Workspace appears. Treat Custom Workspaces as a migration to-do list rather than a permanent information architecture.

Step 6: Curate module sidebars

Review the generated sidebars and rebuild anything that was not carried over. Prefer one clear, curated sidebar per module.

Step 7: Test with real user roles

Test as ordinary users from different departments. Verify:

application visibility;
module visibility;
sidebar contents;
Workspace access;
DocType and Report permissions;
old bookmarks and direct links;
the app icon's landing route;
mobile and smaller-screen behavior.

Step 8: Switch the Desktop page

When staging validation is complete, open Desktop Settings, set Desktop Page to Apps, and save.

This setting affects all users. While the fallback remains available, the site can temporarily return to Desktop Icons without deleting the stored icons or arrangements.

Step 9: Monitor and document

After production rollout, collect feedback from real users, fix missing navigation entries, and document the final module ownership and sidebar structure.

8. Important migration risks

The official migration guide identifies several details worth checking carefully:

Site-level sidebar changes may not be carried over when an app ships a new sidebar for the same module.
Some legacy icons may be hidden if they opened a sidebar that no longer maps cleanly to a Workspace or module sidebar.
Old sidebar records may remain as a read-only archive for recovery purposes.
Existing /desk/... and /app/... links are intended to continue working and may be normalized to the new route structure.
A Workspace without a correct module assignment can be difficult for users to find.

These are strong reasons to test with a copy of production data before switching the whole site.

9. Why this architecture makes sense

A free-form icon grid becomes harder to manage as an ERP grows. Consider a system with:

many installed applications;
dozens of modules;
hundreds of DocTypes;
many Reports and Workspaces;
different access rules by role;
user-specific navigation preferences.

A hierarchy such as:

App → Module → Sidebar → Resource

creates clearer ownership.

It answers practical questions:

Which app owns this functionality?
Which business module does it belong to?
Which sidebar should expose it?
Which users are allowed to see it?
Where should a user land after opening the app?

This structure also makes custom apps easier to reason about and maintain than a growing collection of independent icons.

10. The conclusion for v16.50

The correct interpretation of Frappe / ERPNext v16.50 is not:

Desktop Icons were deleted.

It is:

The old Desktop Icon grid remains temporarily for compatibility.
The new Apps → Modules → Sidebar hierarchy is the target architecture.
Existing sites should migrate deliberately.
New custom apps should build for the new model.

For existing ERPNext installations, there is no reason to panic or delete the legacy configuration immediately. Preserve it, test the conversion, and move users only after the new navigation has been validated.

For developers starting new projects, the direction is already clear: register the application on the Apps screen, define its modules and Dock, and curate one useful sidebar per module.

The practical workflow is:

Back up → Audit → Upgrade on staging → Organize → Test → Switch → Monitor

That approach respects existing users without building new technical debt around a grid that Frappe has officially said will be removed in a future release.

References

Official sources

Selected GitHub issues

#36325 — Caching issue for Desktop Icons — fixed and released in v16.7.0
#36953 — Cannot create a functional Desktop Icon from the list — open at the time of writing
#38292 — Desktop Icon layout, shortcut, and folder issues — open at the time of writing

Issue states can change after publication. Check each issue directly before using its current status in a migration decision.

Author's note

I'm Mohamed Hamed (@m7amedenho), a software developer working with ERPNext and Frappe Framework. I wrote this article to organize what I learned while investigating the navigation changes in v16.50 and to help other developers approaching the same migration.

If you have migrated a customized v16 site to the new navigation, I would be interested to hear which Desktop Icon, Workspace, or Sidebar behaviors required the most attention in your environment.

DEV Community