Desktop Client

The UIS Workspace desktop client for Windows, macOS, and Linux keeps files synchronized between your computer and your UIS Workspace server.

Installation

Download

You can download the latest version of the UIS Workspace Desktop Synchronization Client from the UIS Workspace from download page. Clients are available for Linux, macOS, and Microsoft Windows.

You will also find links to source code archives and older versions on the download page.

Supported server versions

Each desktop client release supports the latest three stable UIS Workspace server major versions at the time of release. See the UIS Workspace Server release schedule for supported major versions.

System Requirements

Windows 10+ (64-bits only)
macOS 12.0+ (64-bits only)
Linux (Ubuntu 24.04 or openSUSE 15.5 or Alma 8 or …) (64-bits only)

For Linux distributions, we support, if technically feasible, the current LTS releases. For BSD, we support them if technically feasible, but we do not test them.

Note

We do not support Citrix.

We will do our best to advise Citrix users from the desktop client point of view.
We will fix issues that are also reproducible on the standard supported systems.
Everything else is outside of our scope.

Install on macOS and Windows

Installation on macOS and Windows is the same as for any other software application: download the program and then double-click it to launch the installation, and then follow the installation wizard. After it is installed and configured the desktop client will automatically keep itself updated; see The Automatic Updater for more information.

For administrator-focused deployment options such as advanced Windows MSI configuration, non-interactive account provisioning, and command-line wizard preconfiguration, see the Admin Manual chapter on desktop client deployment and setup.

Install on Linux

For Linux, UIS Workspace officially provides the desktop client as an AppImage on the UIS Workspace download page.

Some Linux distributions also provide the UIS Workspace desktop client through their package managers. These packages are maintained by the distribution or community, not by UIS Workspace . If you prefer a package-managed installation, refer to your distribution’s documentation.

Linux users must also have a password manager enabled, such as GNOME Keyring or KWallet, so that the desktop client can log in automatically.

Initial Setup

After installation, the initial setup wizard is triggered. In the setup wizard, you can log in to your server, create an account with a provider, and configure which folders to sync. The wizard will guide you step-by-step through the essential configuration options and basic account setup.

First, you need to enter the URL of your UIS Workspace server.

form for choosing between login and registering

If you already have an account on a UIS Workspace instance, click Login to your UIS Workspace . If you do not yet have a UIS Workspace instance or an account, you may need to create one first. Alternatively, you might want to register an account with a provider. Press Create account with Provider in that case.

Note

The desktop client build you are using may have been built without provider support. In that case, you won’t see this page and will immediately see the next page.

Enter the URL for your UIS Workspace instance. The URL is the same URL that you type into your browser when you try to access your UIS Workspace instance.

Now your web browser should open and prompt you to log in to your UIS Workspace instance. Enter your username and password in your web browser and click Grant access when prompted. After you do that, go back to the wizard.

Note

You might not need to enter your username and password if you are already logged in to your web browser.

Select which remote folders to sync, and which local folder to store them in.

On the local folder options screen, you may sync all of your files on the UIS Workspace server, or select individual folders. The default local sync folder is UIS Workspace , in your home directory. You may change this as well.

When you have completed selecting your sync folders, click the Connect button. The client will attempt to connect to your UIS Workspace server. If it is successful, the wizard will close itself. You can then observe the sync activity and open the main dialog by clicking on the tray icon.

Uninstallation

It is safe to uninstall the files desktop client by using the built-in tools within your operating system.

General instructions

In each operating system:

Make sure to quit the desktop client before removing it.
Uninstall the desktop client.
You may also need to take into consideration that uninstalling the desktop client will not remove the user’s configuration file and synced data.

For data removal (sync folders), consider using the server feature remote wipe. This feature is available across all clients.

Below are platform specific instructions.

Windows

There are two ways of removing the desktop client:

Using Add or Remove Programs.
You can use the msiexec command line options:

msiexec /uninstall Nextcloud-x.y.z-x64.msi /quiet``

The user’s configuration is located at %APPDATA%\Nextcloud\nextcloud.cfg.

macOS

Beyond deleting the desktop client from the Applications folder, you may also need to remove all related data, specially if you are using virtual files.

To simply uninstall the software: you can do this from the Launchpad or the Finder.
For the complete removal of all related data, the following commands can be used:

rm -rf "$HOME/Library/Application Scripts/com.nextcloud.desktopclient"*
rm -f  "$HOME/Library/Application Support/CrashReporter/Nextcloud_"*
rm -rf "$HOME/Library/Application Support/Nextcloud"
rm -rf "$HOME/Library/Caches/Nextcloud"
rm -rf "$HOME/Library/Containers/com.nextcloud.desktopclient"*
rm -rf "$HOME/Library/Group Containers/NKUJUXUJ3B.com.nextcloud.desktopclient"
rm -rf "$HOME/Library/Group Containers/com.nextcloud.desktopclient"
rm -f  "$HOME/Library/LaunchAgents/com.nextcloud.desktopclient.plist"
rm -rf "$HOME/Library/Preferences/Nextcloud"
rm -f  "$HOME/Library/Preferences/com.nextcloud.desktopclient.plist"

From version 33.0.0 the user’s configuration is located at $HOME/Library/Containers/com.nextcloud.desktopclient/Data/Library/Preferences/Nextcloud/nextcloud.cfg. On older versions it is located at $HOME/Library/Preferences/Nextcloud/nextcloud.cfg.

Linux

It depends on how you installed the desktop client:

If you are running the UIS Workspace AppImage, you can simply delete the AppImage file.
If you have used your package manager to install the desktop client, you can use it to uninstall the desktop client as well. For example, on Ubuntu you can use the following command:

sudo apt remove nextcloud-desktop

The user’s configuration is located at $HOME/.config/Nextcloud/nextcloud.cfg.

Using the Synchronization Client

The UIS Workspace Desktop Client remains in the background and is visible as an icon in the system tray (Windows, KDE), menu bar (macOS), or notification area (Linux).

Status icon, green circle and white checkmark

The status indicator uses icons to indicate the current status of your synchronization. The green circle with the white checkmark tells you that your synchronization is current and you are connected to your UIS Workspace server.

Status icon, blue circle and white semi-circles

The blue icon with the white semi-circles means synchronization is in progress.

Status icon, grey circle and vertical parallel lines

The grey icon with the parallel lines tells you your synchronization has been paused. (Most likely by you.)

Status icon, gray circle and three horizontal white dots

The gray icon with three white dots means your sync client has lost its connection with your UIS Workspace server.

When you see a yellow circle with the sign “!” that is the informational icon, so you should click it to see what it has to tell you.

The red circle with the white “x” indicates a configuration error, such as an incorrect login or server URL.

Systray Icon

A right-click on the systray icon opens a menu for quick access to multiple operations.

This menu provides the following options:

Open main dialog
Pause sync/Resume sync
Settings
Exit UIS Workspace , logging out and closing the client

A left-click on your systray icon opens the main dialog of the desktop client.

The main dialogs show recent activities, errors and server notifications.

When clicking on the main dialog and then clicking on the avatar of the user, the Settings can be opened.

Configuring UIS Workspace Account Settings

At the top of the window are tabs for each configured sync account, and two others for General and Network settings. On your account tabs you have the following features:

Connection status, showing which UIS Workspace server you are connected to, and your UIS Workspace username.
Used and available space on the server.
Current synchronization status.
Add Folder Sync Connection button.

The little button with three dots (the overflow menu) that sits to the right of the sync status bar offers additional options:

Open Folder
Choose What to Sync (This appears only when your file tree is collapsed, and expands the file tree)
Pause Sync / Resume Sync
Remove folder sync connection
Availability (Only available if virtual files support is enabled)
Enable virtual file support/Disable virtual file support

Open Folder opens your local UIS Workspace sync folder.

Pause Sync pauses sync operations without making any changes to your account. It will continue to update file and folder lists, without downloading or updating files. To stop all sync activity use Remove Folder Sync Connection.

Note

UIS Workspace does not preserve the mtime (modification time) of directories, though it does update the mtimes on files. See Wrong folder date when syncing for discussion of this.

Adding New Accounts

You may configure multiple UIS Workspace accounts in your desktop sync client. Simply click the Account > Add New button on any account tab to add a new account, and then follow the account creation wizard. The new account will appear as a new tab in the settings dialog, where you can adjust its settings at any time. Use Account > Remove to delete accounts.

File Manager Overlay Icons

The UIS Workspace sync client provides overlay icons, in addition to the normal file type icons, for your system file manager (Explorer on Windows, Finder on Mac and Nautilus on Linux) to indicate the sync status of your UIS Workspace files.

The overlay icons are similar to the systray icons introduced above. They behave differently on files and directories according to sync status and errors.

The overlay icon of an individual file indicates its current sync state. If the file is in sync with the server version, it displays a green checkmark.

If the file is ignored from syncing, for example because it is on your exclude list, or because it is a symbolic link, it displays a warning icon.

If there is a sync error, or the file is blacklisted, it displays an eye-catching red X.

If the file is waiting to be synced, or is currently syncing, the overlay icon displays a blue cycling icon.

When the client is offline, no icons are shown to reflect that the folder is currently out of sync and no changes are synced to the server.

The overlay icon of a synced directory indicates the status of the files in the directory. If there are any sync errors, the directory is marked with a warning icon.

If a directory includes ignored files that are marked with warning icons that does not change the status of the parent directories.

Set the user status

If you have the user status app installed on your UIS Workspace server, you can set your user status from the desktop client. To do so, open the main dialog. Then click on your avatar and then click on the three dots. In the menu that opens click on Set status.

Open user status dialog from main dialog.

In the dialog that opens, you can set your online status if you click on either Online, Away, Do not disturb or Invisible. You can also set a custom status message with the text field below or choose one of the predefined status messages below. It is also possible to set a custom emoji if you click on the button with the emoji beside the text input field. The last thing you might want to set is when your user status should be cleared. You can choose the period after which the user status will be cleared by clicking on the button on the left hand side of the text Clear status message after.

If you are happy with the status you have created you can enable this status with the button Set status message. If you had already a status set, you can clear the status by clicking the cutton Clear status message.

Sharing From Your Desktop

The UIS Workspace desktop sync client integrates with your file manager. Finder on macOS and Explorer on Windows. Linux users must install an additional package depending on the used file manager. Available are e.g. nautilus- UIS Workspace (Ubuntu/Debian), dolphin-nextcloud (Kubuntu), nemo-nextcloud and caja-nextcloud. You can create share links, and share with internal UIS Workspace users the same way as in your UIS Workspace Web interface.

In your file explorer, click on a file and in the context menu go to UIS Workspace and then click on Share options to bring up the Share dialog.

From this dialog you can share a file.

General Window

The General window has configuration options such as Launch on System Startup, Use Monochrome Icons, and Show Server Notifications. This is where you will find the Edit Ignored Files button, to launch the ignored files editor, and Ask confirmation before downloading folders larger than [folder size].

Using the Network Window

The Network settings window enables you to define network proxy settings, and also to limit download and upload bandwidth.

Using the Ignored Files Editor

You might have some local files or directories that you do not want to backup and store on the server. To identify and exclude these files or directories, you can use the Ignored Files Editor (General tab).

For your convenience, the editor is pre-populated with a default list of typical ignore patterns. These patterns are contained in a system file (typically sync-exclude.lst) located in the UIS Workspace Client application directory. You cannot modify these pre-populated patterns directly from the editor. However, if necessary, you can hover over any pattern in the list to show the path and filename associated with that pattern, locate the file, and edit the sync-exclude.lst file.

Note

Modifying the global exclude definition file might render the client unusable or result in undesired behavior.

Each line in the editor contains an ignore pattern string. When creating custom patterns, in addition to being able to use normal characters to define an ignore pattern, you can use wildcards characters for matching values. As an example, you can use an asterisk (*) to identify an arbitrary number of characters or a question mark (?) to identify a single character.

Patterns that end with a slash character (/) are applied to only directory components of the path being checked.

Note

Custom entries are currently not validated for syntactical correctness by the editor, so you will not see any warnings for bad syntax. If your synchronization does not work as you expected, check your syntax.

Each pattern string in the list is followed by a checkbox. When the check box contains a check mark, in addition to ignoring the file or directory component matched by the pattern, any matched files are also deemed “fleeting metadata” and removed by the client.

In addition to excluding files and directories that use patterns defined in this list:

The UIS Workspace Client always excludes files containing characters that cannot be synchronized to other file systems.
Files are removed that cause individual errors three times during a synchronization. However, the client provides the option of retrying a synchronization three additional times on files that produce errors.

Virtual Files on macOS

For information about using virtual files integration on macOS, see:

macOS Virtual Files Client

macOS Virtual Files Client

On macOS, our client can also seamlessly integrate UIS Workspace files into macOS as a file provider extension. Any newly configured UIS Workspace account will have the integration enabled by default.

Supported features

Keeping files or whole folders available offline
Freeing up local disk space by evicting local copies without deleting items
Intelligent and automatic local data eviction
File previews within Finder for files which are not downloaded yet
Support for Apple-specific formats, for example Pages, Numbers or Keynote bundles
Support for server-side file locking (if supported by the connected server)
“Edit locally” support
Sharing with other users
Server-side actions integrated directly in Finder’s context menu
Automatic discovery of server-side changes

Configuration

Virtual files-related settings can be adjusted on a per-account basis via the UIS Workspace desktop client’s settings window.

Nextcloud desktop client settings showing the macOS file provider extension toggle

Here the integration into Finder can be enabled or disabled.

When disabling the file provider extension while still having unsynchronized changes, macOS will save the unsynchronized items in a folder that is automatically revealed after the integration is disabled.

Finder integration

On macOS, remote storage like a UIS Workspace files account appears like a dedicated location in the Finder sidebar. The actual location of the content on disk is defined by macOS.

Finder sidebar showing a Nextcloud file provider domain

Note

To accelerate server-side change detection, we recommend enabling the notify_push app on your UIS Workspace server. This app will notify the desktop client of changes on the server as soon as they happen, reducing the time it takes for changes to appear in Finder. Otherwise the client needs to poll the server which will result in an increased delay between a change on the server and its local visibility.

Sync status indicators

Similar to classic synchronization folders, Finder displays status indicators next to items. Unlike the custom indicators in classic synchronization folders, these standardized indicators are provided by macOS to ensure a consistent appearance across all cloud storage apps which a user may use on their system.

Cloud with downward arrow: The item and its descendants are not downloaded yet. They can be downloaded, assuming a network connection is available.
Outlined cloud: The item is not fully uploaded yet in its current local state.
Strikethrough cloud: The item is excluded from synchronization.
Pie chart: The item is currently being uploaded or downloaded, and the progress is visualized.
Filled circle with a pin: The item is available offline and will be kept locally.
No icon: The item is available offline and up to date.

Context menu actions

The file provider extension also provides special UIS Workspace features through the context menu in Finder.

Keep Downloaded

Files and folders can be marked to be kept downloaded and available offline permanently. If this is chosen on folders, it will also apply to all their contents. This is especially useful for users with limited or no network access, as it ensures that they can always access their important files without needing to worry about connectivity. macOS will not free up local disk space by evicting items which are marked to be kept downloaded, even if they have not been accessed for a long time.

This can be undone by selecting “Allow automatic freeing up space” on the same items.

To always keep everything in an account available locally, you can select “Always keep downloaded” on the location root in the Finder sidebar.

Locking

If the server supports file locking, the client will offer manual locking and unlocking of files in Finder.

Sharing

macOS Finder share management panel for a Nextcloud file showing existing shares

When the server supports sharing and the item is allowed to be shared, then you can create new shares or manage existing shares for an item directly from the context menu in Finder, as in the Nextcloud web interface.

File actions

If the server has apps installed which provide file actions for the selected file types, these actions will also be available in the context menu in Finder. This allows you to use server-side features of your Nextcloud instance directly from the Finder.

Known issues

macOS Extensions conflict

Due to technical limitations in macOS which are imposed by Apple, it is not possible to have the Finder integration for classic sync folders running in parallel to an enabled virtual files integration. This means that item decorations and context menu options will be unavailable for classic sync folders while the file provider extension is enabled.

Alias files

When opening a macOS alias file stored on Nextcloud for the first time on a device where it has not yet been downloaded, the file may open as a binary document in a text editor instead of jumping to its target. This happens because macOS decides how to open a file before downloading it, and alias files carry no recognisable file extension or type information on the server — the only way to identify them is by reading their content. Once the file has been opened or downloaded once, Nextcloud Desktop learns that it is an alias and stores that information locally, so all subsequent opens will work correctly. To avoid the issue entirely, right-click the alias file in Finder and choose Keep Downloaded before opening it for the first time.

Using the Command-Line Client

The Nextcloud Client packages contain a command line client, nextcloudcmd, that can be used to synchronize Nextcloud files to client machines.

nextcloudcmd performs a single sync run and then exits the synchronization process. In this manner, nextcloudcmd processes the differences between client and server directories and propagates the files to bring both repositories to the same state. Contrary to the GUI-based client, nextcloudcmd does not repeat synchronizations on its own. It also does not monitor for file system changes.

Install

OS	Package
Alpine	https://pkgs.alpinelinux.org/package/edge/community/x86_64/nextcloud-client
Debian	https://packages.debian.org/search?suite=all&arch=any&searchon=names&keywords=nextcloud-desktop-cmd
Fedora	https://packages.fedoraproject.org/pkgs/nextcloud-client/nextcloud-client/
Ubuntu	https://packages.ubuntu.com/search?keywords=nextcloud-desktop-cmd
Ubuntu (PPA)	https://launchpad.net/~nextcloud-devs/+archive/ubuntu/client
Windows	https://nextcloud.com/install/#install-clients

Usage

To invoke nextcloudcmd, you must provide the local and the remote repository URL using the following command:

nextcloudcmd [OPTIONS...] sourcedir nextcloudurl

where sourcedir is the local directory and nextcloudurl is the server URL.

Other command line switches supported by nextcloudcmd include the following:

--path: Overrides default remote root folder to a specific subfolder on the server(e.g.: /Documents would sync the Documents subfolder on the server)
--user, -u <user>: Use user as the login name.
--password, -p <password>: Use password as the password.
-n: Use netrc(5) for login.
--non-interactive: Do not prompt for questions and tries to read $NC_USER and $NC_PASSWORD from the environment.
--silent, --s: Inhibits verbose log output.
--trust: Trust any SSL certificate, including invalid ones.
--httpproxy http://[user@pass:]<server>:<port>: Uses server as HTTP proxy.
--exclude <file>: Exclude list file
--unsyncedfolders <file>: File containing the list of unsynced folders (selective sync)
--max-sync-retries <n>: Retries maximum n times (defaults to 3)
-h: Sync hidden files,do not ignore them

Credential Handling

nextcloudcmd requires the user to specify the username and password using the standard URL pattern, e.g.,

$ nextcloudcmd /home/user/my_sync_folder https://carla:secret@server/nextcloud

To synchronize the Nextcloud directory Music to the local directory media/music, through a proxy listening on port 8080, and on a gateway machine using IP address 192.168.178.1, the command line would be:

$ nextcloudcmd --httpproxy http://192.168.178.1:8080 --path /Music \
              $HOME/media/music \
              https://server/nextcloud

UIS Workspacecmd will prompt for the user name and password, unless they have been specified on the command line or -n has been passed.

Exclude List

nextcloudcmd requires access to an exclude list file. It must either be installed along with nextcloudcmd and thus be available in a system location, be placed next to the binary as sync-exclude.lst or be explicitly specified with the --exclude switch.

The required file content is one exclude item per line where wildcards are allowed, e.g.:

~*.tmp
._*
]Thumbs.db
]photothumb.db
System Volume Information

Example

Synchronize a local directory to the specified directory of the UIS Workspace server

$ nextcloudcmd --path /<Directory_that_has_been_created> /home/user/<my_sync_folder> \
https://<username>:<secret>@<server_address>