FAQ

Subsurface provides recreational scuba divers, tech divers, and diving professionals with an easy to use interface for planning and logging and organizing dives. Dives can be entered manually, via spreadsheets, directly from some other dive logging software, and most importantly from many dive computers. What if you change dive computers? This is no problem with Subsurface as it is not tied to a specific dive computer manufacturer. Tech divers will appreciate the dive planner which allows you to plan using VPM-B or Bühlmann ZH-L16. Testing bailout gases, comparing different gas mixes and gradient factors, and finally printing the plan is made easy. Subsurface is free and available on multiple platforms making it the perfect software for a wide range of scuba divers.

Subsurface runs on Windows 10 and newer, MacOS 10.15 and newer, and many flavors of Linux. Mobile versions of Subsurface are available for Android and iOS allow a portable platform for viewing your dive log and performing minor edits; depending on your OS/hardware comby, you may even be able to download dive data directly from your dive computer using Subsurface-mobile.

We provide Linux packages for some Linux distributions (currently Ubuntu and Fedora, Debian is supported by a community contributor). Additionally, a Snap package and a generic AppImage are available for other distributions of Linux. Details on where to find Subsurface for your OS are on our current release page.

Subsurface-mobile for iOS is available in the iOS App Store. Subsurface-mobile for Android is available as sideloaded APK at our current release page.

Subsurface is open source software. It's free to use. It's written by a group of enthusiasts who do this in their spare time - including providing the Subsurface Cloud storage and all the other infrastructure. Please understand that this also means that they will respond to your requests when they have time, and they generally don't appreciate being treated like the support team of a commercial vendor. If you'd like a commercial dive log program, there are plenty others to choose from.

If you would like to contribute and help, there are many ways to do so. Our 'Contribute' page lists a few options and provides information on how to get started.

As mentioned in the previous question, Subsurface is written and maintained by volunteers. It also has several ten thousand users. The current feature set aims to find a reasonable balance between a user experience that is easy to understand, and addressing the most commonly requested features. New features often get rejected if none of the existing developers feel strongly that they would make a significant difference to the majority of our users.

You are of course invited and encouraged to provide an implementation for your desired new feature. Please take a look at our code contribution page on GitHub.

Most likely you are expecting the gas consumption calculation to follow the naive ideal gas laws. Unfortunately, real gases aren't ideal gases. And Subsurface takes the compressibility of gases into account.

Download the installer from our current release page and double-click on it. You will get a warning that the installer is from an unknown publisher (but should identify that publisher as Dirk Hohndel / DH Consulting). Please click Yes to allow installation. Next you are presented with the license for Subsurface, after that you can choose where you would like to install Subsurface (the default should be reasonable in most cases) and the Start Menu Folder where a shortcut to call Subsurface and an entry to uninstall Subsurface will be installed.

For technical reasons, some of the Windows binaries you can download from our website aren't signed at all, in which case Windows provides more and stronger warnings when trying to use them. As long as you download the binaries from this website they are safe and do not contain any malware.

Subsurface runs on Windows 10 and newer. It should still run on Windows 8 (but then, why would you want to run that). Older versions aren't supported anymore.

The logs are in C:\Users\Home\AppData\Roaming\Subsurface in the two files subsurface_out.log and subsurface_err.log

Great question - typically those are specific to the combination of dive computer and download cable that you use. And it's really hard to give universally correct answers.

Installing the vendor provided dive log software often is enough to trigger an install of those drivers, but sometimes things are a bit more complicated. Searching the User Forum often helps.

If you get a warning message or if Subsurface is blocked by your anti virus (AV) software, that is almost certainly a false positive. Subsurface is not built on a Windows machine, it is cross built from source on Linux on a well maintained and clean server image.

Most/all Windows Anti-Virus software packages support an “add exception” feature, which skips an executable from being scanned. Try adding Subsurface to the list of non-harmful software. If the Subsurface installer download is detected as malware, please temporary disable your AV software until Subsurface is installed

In either case, please inform your AV software vendor of a “false positive” as we assure your that Subsurface is not malware.

This can have many reasons, but a really odd one we have found is that some anti-malware products on Windows seemingly randomly decide that the traffic between Subsurface and the cloud server is an indication of malware activity and interrupt the transmissions. This can lead to cloud storage corruption and prevents things from working. You may have to add an exception for Subsurface to your hyper-aggressive anti-malware tool.

Download the installer DMG from our current release page and open it. Drag the Subsurface icon on to the Applications folder icon.

When opening the Subsurface app for the first time, you will get a warning that this binary was downloaded from the internet. Depending on your settings and on whether or not this is a signed DMG, macOS will allow you to simply click Ok to open the app.

For technical reasons, some of the macOS DMGs you can download from our website aren't signed at all, in which case macOS will force you to go through the System Preferences / Security in order to allow you to start Subsurface. As long as you download the DMG from this website it is safe and does not contain any malware.

Subsurface runs on both Apple Silicon (M1/M2/M3 CPUs) and Intel Macs running macOS 10.15 and newer. On Apple Silicon Macs Subsurface currently runs in x86_64 emulation mode via Rosetta 2. Work on fat binaries with native support for both x86_64 and Apple Silicon CPUs has been started but for technical reasons currently doesn't create binaries with a great user experience.

Apple stopped supporting macOS 11 and older. We are trying to keep making binaries for 10.15 and 11 available while we can, we are no longer are able to support older versions of macOS.

This has been an ongoing issue for a while; it seems to work fine for many/most users, but some cannot seem to get Subsurface on their Mac to talk to BLE dive computers. For those people, right now the only option is to download using a mobile device / Subsurface-mobile and sync their dive log using Subsurface Cloud.

Subsurface on the Mac does not support IRDA based dive computers. This is an issue of missing support libraries for us to use -- other dive log software may have implemented their own IRDA stack on the Mac, we have not. Subsurface on Windows still supports IRDA based dive computers for now.

Subsurface can run on most Linux distributions. The project actively maintain builds for current Ubuntu and Fedora releases. A community contributor maintains Debian packages. There is also a Subsurface Snap and an AppImage for other distributions. Generally try a distribution specific binary first. If that doesn't work, try the Snap or the AppImage.

Adding support for another Linux distribution is generally a lot of work and given the tiny user numbers not likely to happen. But please, talk to us if you think there is a distribution that we should add instead of the ones that we currently support.

If you would like to contribute and help, this is a perfect opportunity to do so. Please take a look at our code contribution page on GitHub.

Yes, generally this is pretty easy (assuming you are somewhat familiar with C/C++ development under Linux). The INSTALL file in the source directory should get you started. Reach out to the developers if you need help beyond that (because likely that means we need to update the INSTALL file...).

If you would like to contribute and help, this is a perfect opportunity to do so. Please take a look at our code contribution page on GitHub.

iOS users can simply install the Subsurface-mobile app that is available in iOS App Store. There is still an older version of Subsurface-mobile available in the Android Play Store, but because of the excessive bureaucracy and constantly changing rules and requirements associated with the Google Play store, we currently aren't able to update this package (and expect it to become unavailble at some point). To work around this, we have made an Android APK package available on our current release page that can be side-loaded on most Android devices.

Once you have installed Subsurface-mobile on your device, enable cloud storage in Subsurface from your desktop or laptop and store your dive information in the Subsurface cloud. The dives will now be available on your mobile device as well. Subsurface-mobile does not support all the features of the desktop version of Subsurface. For example dive planning is not available in Subsurface-mobile.

From all other devices (including tablets and phones with OSs that we don’t support with Subsurface-mobile), you can open our cloud website and log in with the same email address / password. This allows you to access your dive data from any device with a web browser.

The side-loaded APK should work with Android 8.0 and newer. Older Android versions are known not to work with the Subsurface Cloud.

Bluetooth and BLE based dive computers as well USB serial dive computers should generally work (assuming they are supported by Subsurface at all, of course). What doesn't work are other USB devices like USB HID (e.g., Suunto EON Steel family via cable - BLE works), USB storage (e.g., Uemis Zurich), or MTP (e.g., Garmin).

Only dive computers that support download via BLE (that are already supported in Subsurface) work with iOS devices. The Garmin dive computers are the exception to this rule, they aren't supported on iOS at all. No cable based downloads are possible.

With the desktop version you can check from the Help menu: simply select “Check for updates”. The iOS version notifies you via the regular AppStore mechanisms. A notification mechanism for Android is under development.

You can also check the current release page to look at our reasonably frequent (“weekly”) updates.

There are multiple ways to import into Subsurface. Details can be found in the User Manual.

Manually logged dives can directly be entered in the UI or (in the desktop version) imported from various forms of spreadsheets.

Dives can be downloaded from supported dive computers. Details vary greatly depending on how the dive computer connects to your computer or mobile device.

It is also possible to import dive data from other software or websites. See the User Manual for the most up to date information on this – it can be found in Section 5.3.

This is a typical question for side mount divers or some tec divers. Subsurface supports having more than one tank with the same gas, even if some dive computers don’t. Simply add a gas change to your second tank of the same gas as both tanks will be included in the gas use calculations. In order to add gas changes simply right-click on the profile at the appropriate spot and you will be offered to add such an event.

If you have pressure transmitters on multiple tanks with the same gas, the situation is slightly more complicated. The easiest way to ensure that there is no confusion when importing these dives is to assign slightly different gasses to those tanks, e.g. oxygen contents of 21% and 22% for two tanks holding air.

Obviously there can be many reasons for this. If your dive computer connects via cable, clean the contacts and make sure they are dry. Repeat if necessary. Make sure the connector is firmly connected. Wiggle it. Seriously. Make sure the dive computer is in transfer mode (this isn’t necessary for all dive computers but for many common ones). Check with other software that the download works in general. Try another cable. Check your battery. There are some dive computer (especially earlier Suunto models) that will happily work with a low battery, but will fail to transfer dives to a connected PC unless the battery is changed.

There are many more potential issues with Bluetooth or BLE dive computers. Please see our user manual for pairing with such devices and troubleshooting suggestions.

The CSV import has a couple of caveats. You should avoid some special characters like ampersand (&), less than (<), greater than (>) and double quotes (“), the latter if quoting text cells. The file should use UTF-8 character set, if having non-ASCII characters. Also the size of the CSV file might cause problems. Importing 100 dives at a time (without dive profile) has worked previously, but larger files might exceed limits of the parser used. When having problems with CSV imports, try first with a smaller sample to make sure everything works.

Potentially the best way to achieve this is to use multiple user accounts on the computer, all operating systems have built-in support for multiple users. This way the Subsurface configuration for each user is truely separated.

Another option is to store logs of different users to separate log files. From Subsurface, you can open individual files for different divers and multiple users are supported quite well, the downside of this approach is that it's incompatible with Subsurface cloud storage.

A blend of these approaches where you want multi-user Subsurface support within a single computer user account can be achieved as well. Subsurface has the ability support user profiles, simply launch Subsurface with the --user flag e.g. subsurface --user=joebloggs. From this user-specific workspace you can then open either locally stored or cloud hosted dive logs. You can then create different desktop shortcut icons that include this command line flag in order to make the experience more user friendly.

This is supported in the desktop version of Subsurface. Select the dives you want to load and associate the pictures with. Then right click on one of the selected dives and select “Load images” from the popup menu. This will bring in a file selection dialog where you can select one or more pictures. When the selection is done and hit Open and you get a new dialog where you can shift the times of the images (in case of inconsistent clocks between camera and dive computer). Once you confirm this, the pictures are loaded and associated with the right dives and shown (as thumbnails) in the respective dive profiles.

If you are having trouble with loading the images, check that you have at least one of the following tags in the Exif headers: DateTimeOriginal or DateTime. We take the time from these fields to detect if the image was taken during the dive or not. If the picture is edited, make sure that the original Exif information is stored in the new/edited image in order for it to be loaded properly. Most modern photo editing software does that correctly by default.

Many common programs are already supported and we are always happy to try to add new ones. If your old log software supports exporting the log book, we might well be able to import that (for example via CSV files or UDDF). However, usually support for importing the native format will help you to get more complete information into Subsurface. To implement support for the log format, we will need a sample log file. It would be great to have also a screenshot from the original log software or description of the dive that is shown on the sample log. Preferably we would like to have a reasonably simple dive to get basic support and another dive that has as many features enabled as possible (e.g. gas changes during the dive). Please post this information to the user forum or send it to the developer mailing list subsurface@subsurface-divelog.org. Unfortunately some of the log formats we have not been able to decipher (as some vendors have decided to encrypt their log files to increase the degree of lock-in of their customers), so there are no guarantees that this will bring support for your old log software, but it is worth a try.

Dive history is different than the dive profiles on the log. The history only keeps track of the total number of dives and total amount of time spent below surface. The logs, on the other hand, store the dive profile, but they have limited amount of memory to do so. The exact amount of dive profiles that can be stored on the device depend on sample interval and duration of the dives. Once the memory is full the oldest dives get overwritten with new dives. Thus we are only able to download the last 13, 30 or 199 dives.

If you have downloaded your dives to different dive logging software before they were overwritten, there is a high chance that Subsurface can import these. However, if the logs are only on your dive computer, they cannot be salvaged after being over written by new dives.

If you have configured your correct user credentials to Subsurface and cloud authentication still fails, try to change the password on via the password reset on our website. If your credentials are still not working or there is something else wrong, contact Dirk to sort it out.

Subsurface can store your dive log securely in the Subsurface Cloud, backing up your data, allowing you to access your dive logs on a desktop, Android, or iOS device. Additionally there is a read only web view available at the cloud webpage.

This is the only cloud solution available, which allows the developers the ability to enhance Subsurface, fix issues, and support users (with your permission) if something goes wrong with the Cloud Storage. The incremental effort to support additional cloud backends is substantial, while at the same time making it much harder for us to help users who run into trouble. In the end this is not a useful trade-off for us to make, so other cloud solutions continue to not be supported.

If you only use Subsurface on the desktop and wish to backup your log on a remote storage server, the documention describes how to store your XML data on DropBox or other similar services such as OwnCloud, TeamDrive, MiniBox, etc.

We support a large number of dive computers already and are always happy to add support for more. Please contact us via the User Forum so we can try to help. Some vendors have actively helped us in our work and adding support for new models from those vendors is usually easy. Other vendors are more neutral, some are actively hostile. Without help from the vendor it can be rather challenging to reverse engineer the transfer protocol and the dive encoding, but with sufficient help from you it is often possible to do so.

A good starting point is often to send us a libdivecomputer log and dump (you can pick those in the dive computer download dialog) when connecting to the dive computer using a similar existing model (if possible). But generally it might make the most sense to first reach out in order to avoid wasting your time.

If you would like to contribute and help, there are many ways to do so. Please take a look at our 'Contribute' page.

Most of the download cables are FTDI based and need the appropriate drivers installed. Some other third party cables need different drivers. Without those drivers, the dive computer device won't show up. Once you can see the device (COMn or /dev/tty...), if you get timeouts or data errors, see the data error question below.

Astoundingly commonly the reason are wet or dirty contacts or a low battery. It doesn't matter if the dive computer turns on. Download mode often requires much higher stable voltage to work. And sadly we even have seen situations where the vendor dive log will work (because it can do a much better job at 'error correction'), but Subsurface won't download until you have a fresh battery and really clean and really dry contacts.

Yes, yes they are. Since Subsurface supports BLE download from many different dive computers from many different vendors, the code is generally not as well tuned for a specific dive computer as the vendor app can be. So unfortunately these downloads are painfully slow. Usually downloading a few dives a day is tedious, but not horrible. But especially a first download with a hundred or more dives can take an hour and longer - and sometimes it is hard to complete the download without running into errors that lead the download to abort. It really pays off to download early and often.

If the dive computer offers a way to download with a USB cable (in addition to BLE, like for example the Suunto EON Steel family), that is definitely preferable especially for that first download.

The Descent dive computers are only supported on Windows, macOS, and Linux, and only for cable based download. Based on a specific request from Garmin, we will not be able to support BLE downloads on any platform.

If for some reason you cannot get regular downloads to work, but have access to the `.FIT` files, you can still use Subsurface to import those, still using the download code. Simply create a folder ...somepath.../Garmin/Activity and copy the .FIT files into that folder. Now start a Subsurface download and enter ...somepath... (without the Garmin/Activity part) in the Connection field and press Download.

The Descent Mk2/Mk3 is an MTP device which causes occasional problems when trying to download from it using Subsurface. MTP supports only a single connection, so other MTP apps may prevent Subsurface from talking to your dive computer. Exit all other apps that might try to connect to a media device, like for example the Android File Transfer.

You need the correct USB driver in order to talk to the Descent Mk2/Mk3.

Please download Zadig 2.6 and run it, plug in the Descent and select MTP, wait for Zadig to offer the Descent as an option (this may require an unplug / replug cycle), select the Descent and tell Zadig to install `libusb-win32` (wait for this to finish which takes a while), unplug the Descent and plug it back in, again selecting MTP. Now Subsurface is able to download from it (don't enter anything in the connection field)