OmniFocus 4 Reference Manual

Managing Your Data

OmniFocus stores all the information that you enter into a file on your system, titled OmniFocus.ofocus (technically, a bundle — which is a folder of files that looks like a single file). On a Mac, you can see the data file by selecting Show “OmniFocus.ofocus” in Finder from the File menu. On an iPhone or iPad, you can see the data file by using, and navigating to On My iPhone/iPad > OmniFocus > OmniFocus.ofocus (though the name will likely display without the .ofocus portion). It is possible to have both OmniFocus 3 and OmniFocus 4 installed and syncing on the same device, so to make it easier to tell the folders apart, the OmniFocus 4 folder will also contain a file with the title OmniFocus 4 Documents.

Setting up OmniFocus 4

When you first launch OmniFocus you’ll be asked to set up Sync. Syncing is important as an additional layer of backup for your data, and enables several of the advanced features of the app such as email capture.

If you’re planning to sync, we recommend setting up sync as part of the first launch process, to ensure as smooth a transition as possible between versions. If you choose to set up sync later, the same options you see during first launch are available in Sync settings.

Upgrading from OmniFocus 3

OmniFocus 4.0 does not contain any changes to the OmniFocus data structure and is fully sync compatible with the latest releases of OmniFocus 3. Future OmniFocus 4 updates may require you to migrate your data to an updated format.

We have updated how the Archive Old Items… and Open Archive… commands work, to better support importing existing Archive files from older versions of OmniFocus. More information is available in the Importing an Existing Archive section of Archiving in OmniFocus.

Upgrading While Syncing

If you are currently syncing OmniFocus 3, then upgrading to OmniFocus 4 is easy:

  1. Launch OmniFocus 4 on your Mac, iPhone, iPad, or Apple Watch. If this is the first time you have launched OmniFocus 4, complete the setup.
  2. When you reach the Sync Setup screen, sign into the same sync account you use for OmniFocus 3, whether that is an Omni Account or an Advanced (WebDAV) server account.
  3. You will be prompted to Add tutorial project, which will help get you quickly acquainted with OmniFocus 4… so you can enjoy the new and updated features!
  4. If you are using a Mac, and have an existing Archive, please read Importing an Existing Archive.

Upgrading on a Mac Without Syncing

Upgrading from OmniFocus 3 to OmniFocus 4 on a Mac without syncing requires exporting your existing OmniFocus data from OmniFocus 3, adding it to OmniFocus 4, and then importing any existing Archive file. This will allow you to use OmniFocus 4, while leaving OmniFocus 3 unchanged.

  1. Launch OmniFocus 3 on your Mac.
  2. Select Export… from the File menu, choose a location that is easy to find (such as the Desktop), select the file format option for Backup Document (OmniFocus), then click the Save button. This will save an OmniFocus.ofocus-backup file in your chosen location.
  3. Quit OmniFocus 3, so you’re working with a single version of the app.
  4. Launch OmniFocus 4 on your Mac. If this is the first time you have launched OmniFocus 4, complete the setup.
  5. When you reach the Sync Setup screen, tap the Skip button, and confirm that you would like to continue without syncing.
  6. You will be prompted to Add tutorial project; choose either option (as this data will be replaced), and then tap on Launch OmniFocus. You should be viewing a new data file in OmniFocus 4.
  7. Drag the OmniFocus.ofocus-backup file on top of the OmniFocus 4 app icon in the Dock or Applications folder, click on the Revert to This Backup button that will present in a bar at the top of the window, and then confirm that you’d like to revert to the backup.
  8. Your OmniFocus 3 data should now be in OmniFocus 4, and you can close the OmniFocus Backup document.
  9. The first time you use Archive Old Items… or Open Archive… in OmniFocus 4, it will offer to import a copy of your existing archive from OmniFocus 3 (or OmniFocus 2). Please read the Archiving in OmniFocus section, with special attention to Importing an Existing Archive.

Upgrading on an iPhone or iPad Without Syncing

Manually upgrading from OmniFocus 3 an iPhone or iPad requires copying your primary OmniFocus data; this will allow you to begin using OmniFocus 4, while leaving OmniFocus 3 fully operational.

  1. Install and launch OmniFocus 4.
  2. Complete the setup for OmniFocus 4.
  3. When you reach the Sync Setup screen, tap the Skip button, and confirm that you would like to continue without syncing.
  4. You will be prompted to Add tutorial project; choose either option (as this data will be replaced), and then tap on Launch OmniFocus. You should be viewing a new data file in OmniFocus 4.
  5. Force quit OmniFocus 4 (See Quit and reopen an app on iPhone or Quit and reopen an app on iPad).
  6. We’re now going to find your current OmniFocus 3 data. Let’s start by opening
  7. Navigate to On My iPhone/iPad > OmniFocus. Note that there should be two OmniFocus folders: one will contain your OmniFocus 3 data, and one will contain your OmniFocus 4 data. You are looking for the folder that contains the OmniFocus 3 Documents file.
  8. There should also be an OmniFocus.ofocus file in this folder (which may display as OmniFocus, depending on your View Options in Press and hold on OmniFocus.ofocus, and select Copy.
  9. Navigate to the other OmniFocus. This one should contain a OmniFocus 4 Documents file.
  10. Press and hold below the file list, and select Paste. Your iPhone or iPad will prompt you to Replace or Keep Both; select Replace.
  11. Launch OmniFocus 4, and your OmniFocus 3 data should be ready to go!

How OmniFocus Sync Works

With sync enabled in OmniFocus, a sync server you choose keeps a copy of your database, so that it’s always available wherever you are. With each sync, OmniFocus compares your local data with what’s on the server and updates each as needed.

OmniFocus automatically syncs whenever it’s connected to the internet. When connected, OmniFocus sends new changes to the sync server after one minute, or when opening or closing the app. At a minimum, OmniFocus checks with the server every hour, even if nothing has changed on the device. This helps ensure that your data from OmniFocus is always safe, secure, and most importantly — up to date.

If you’ve made changes you want to view immediately on another device, you can perform a manual sync by choosing Sync Now from the File menu (Command-S), click the Sync button in the toolbar, or pull down to sync on your iPhone, before switching devices. This syncs your latest changes up to the server, so that when you launch OmniFocus on the other devices, all you have to do is sync to ensure that all of your changes are there… and remember that sync also normally happens when you open the app, so using Sync Now on the second device probably won’t be necessary.

OmniFocus uses push notifications for even more robust synchronization support. This feature notifies OmniFocus on your other devices that a sync is needed, whenever you make a change. With push notifications, manual syncing should rarely be required. See our OmniFocus Push-triggered sync support article for more information on how it works.

For options related to push notification sync, select the Push option in Sync settings.

Encrypted Sync

OmniFocus uses HTTPS to encrypt your data while communicating with sync servers that support it (including the Omni Sync Server). Additionally, all current OmniFocus databases set up to sync with remote servers are also encrypted prior to transit, and remain encrypted on the server.

Encryption was introduced in OmniFocus 2.6 for Mac and OmniFocus 2.15 for iOS. If you are upgrading from a previous version of OmniFocus, your database will require migration.

Encryption is done by OmniFocus on your Mac, iPhone, iPad, or Apple Watch at the time the data is transmitted to the sync server. This means that regardless of the sync destination (Omni Sync Server or another WebDAV server), encryption-based security is preserved. Though your database is encrypted while on the server, OmniFocus doesn’t actively encrypt data while it is stored on your local device, instead deferring to any system-level encryption you have in place.

Technical details of the encryption scheme for OmniFocus can be found in this forum post.

Setting a Separate Encryption Passphrase

By default, OmniFocus encrypts your database on the server using the password you chose when setting up your sync account. When selecting the Encryption row of Sync settings, the resulting view will confirm Encryption active and Passwords are linked. For an extra layer of security, you can use a distinct encryption passphrase by clicking or tapping on Change Passphrase.

When you click Change Passphrase, you are prompted to enter a new passphrase, which will be used to encrypt your database on the server. After setting a new encryption passphrase the Encryption settings will update to read Passwords are distinct. You can link them again by clicking Link Passwords, and entering your current encryption passphrase, or change the encryption passphrase to something new using Change Passphrase.

If you change the encryption passphrase on one device, all of the other devices that you are syncing will prompt you to enter the new passphrase, before that device can receive further updates from the server. This is to guarantee that your end-to-end encryption remains secure across all devices.

Sync Settings

Establishing a cloud-connected copy of your database is a great way to keep OmniFocus in harmony across all your devices. The Sync tab has the options you need to set up your sync account. Even if you’re only using OmniFocus on a single device, we recommend setting up sync for the automated data backup it provides. There are three primary states in this collection of settings:

If you choose to sync, keep your sync password (and separate encryption passphrase, if you use one) in a safe place. If you lose these, you’ll lose access to your data. While our Support Humans can help you reset the password for your Omni Account, it is not possible to reset your encryption phrase, if you have lost it.

If you select to sync using either an Omni Account or Advanced (WebDAV) host, there are several additional settings that become available:

Selecting the Sync row (which shows which kind of account you are using) will show the following information in the right pane (Mac), or on a second screen (iPad or iPhone):

Omni Account

Advanced (WebDAV)

Archiving in OmniFocus

After using OmniFocus for some time, your OmniFocus database may become quite large. This can affect sync times and performance, especially if you are syncing with an iPhone, iPad, or Apple Watch. Most of your data is likely to be completed or dropped items, which you rarely need to reference, so OmniFocus includes an option to move some of that data to an Archive file. This gives you the option to review your older data when needed, while keeping your active data as streamlined as possible.

We have updated how the Archive Old Items… and Open Archive… commands work, as of OmniFocus 4.0.3, and the information in this section reflects that update.

To archive your old data, choose Archive Old Items… from the File menu. A sheet appears with a date field; any items completed before that date, or dropped items that haven’t been changed since that date, will be moved to the archive.

Creating an Archive

The first time that you use Archive Old Items… or Open Archive… in OmniFocus 4, you will be asked to choose a folder where you would like your OmniFocus archive to be stored. This may be a folder with an existing archive, or it may be a folder in which you would like to create a new archive.

OmniFocus 4 supports storing your OmniFocus archive anywhere on your local system, instead of requiring the archive to be stored in the same location as your primary OmniFocus data. Two places to consider are the OmniFocus folder which is automatically created in iCloud Drive, or in an OmniFocus folder that you create in your Documents folder.

Once you have selected a location for your OmniFocus archive, that location will be used each time you Archive Old Items… or Open Archive…. If you would like to change this location, move your current OmniFocus archive file (Archive.ofocus-archive) out of the selected folder. The next time you use an archive-related command, OmniFocus will prompt you to select a new location.

Importing an Existing Archive

If you would like to import your existing Archive file from OmniFocus 4, OmniFocus 3, or OmniFocus 2, but don’t yet want to archive additional items, select Open Archive… from the File menu. If you would like to import your existing Archive, and also want to archive additional items, select Archive Old Items… from the File menu.

You must then select the location where you want the imported Archive file to be stored (not the location of the Archive file to import). If you have recently installed and configured OmniFocus, you will likely be shown a location in iCloud Drive. You are welcome to choose any location in iCloud Drive, or on your local hard drive, but please read the note about Cloud Storage and File Sharing before selecting another cloud storage location.

As long as the location you have chosen to store your imported Archive file doesn’t already contain an OmniFocus 4 Archive file, OmniFocus 4 will search for an OmniFocus 3 archive; if it can’t find one, it will search for an OmniFocus 2 archive. You won't be asked where to select an import location, as OmniFocus 4 already knows where to look. If an existing Archive file is found, OmniFocus 4 will offer to import it, specifying which version of OmniFocus last updated the archive; if multiple Archive files are found, OmniFocus 4 will offer to import the most recent.

Depending on which command you selected from the File menu, you will be presented with options to Import Archive, Create New Archive, or Cancel; please read the available options, and select the best choice.

If you have an Archive file that you would like to import, but which is no longer stored in the default location for an earlier version of OmniFocus, you can still import it. Place it in the same folder you are going to select after using either Open Archive… or Archive Old Items…; OmniFocus 4 will detect that it is from an earlier version, and offer to import it.

Restoring from an Archive

If you ever want to look at your archived data, choose Open Archive… from the File menu; your archive opens in its own window. To retrieve items from an archive you are browsing, drag and drop them into the desired location in your main OmniFocus window (copy and paste works, as well). In either case, a copy remains behind in the archives; the archived copy can be retained as a record or manually deleted to keep things tidy.

Backups of OmniFocus Data

Backups are handled differently on a Mac than they are an iPhone or iPad, but on every device our goal to ensure that your data is safe, and can easily be restored, if needed.

Backups on Mac

On a Mac, OmniFocus automatically backs up your data once every two hours, and keeps up to 100 backups of your data at a time. This is about two weeks worth if you run OmniFocus continuously, but is more for most people, since backups do not happen unless OmniFocus is running. Backups are also made prior to changing sync accounts, migrating your data, and even before restoring from a backup.

To restore a backed-up version of your database, choose Show Backups in Finder from the File menu, then double-click on the backup that you would like to view. It opens in its own separate OmniFocus window, so you can determine if it is the backup that you want to use. If you’d like to use this backup, click the Revert to This Backup button to replace your primary OmniFocus data with the data contained in the backup. If you are syncing, this will also force all of your other devices to re-sync, bringing them all up to date.

Backups Folder

OmniFocus 4 changes where your backups are stored, to make it easier to find them, or to include them in your Mac backups.

If you are not syncing your Desktop & Documents then you will have a special OmniFocus folder inside your Documents folder, that contains a Backups folder. This folder isn't actually part of your Documents folder, but is in a special location inside the OmniFocus storage on your system, which allows macOS to show it here.

If you are syncing your Desktop & Documents (see the Store your Desktop and Documents folders in iCloud Drive section of the Apple User Guide’s Store files in iCloud Drive on Mac), then this folder can be found in On My Mac, which you can add to your Finder sidebar in Finder Settings (see the Apple User Guide article Customize the Finder sidebar on Mac).

Backups on iPhone and iPad

On an iPhone or iPad, OmniFocus automatically backs up your data once per day, and can store backups on your local device, or in iCloud Drive. More information about using Backups on an iPhone or iPad can be found in the Backups settings section.

Migrating Your Data

When you update from earlier to later versions of OmniFocus, you may be prompted to migrate your database to a format capable of supporting the features of the latest version of the app. As noted above, the initial release of OmniFocus 4 is fully sync compatible with the latest release of OmniFocus 3, but if you have been syncing with older versions of OmniFocus, then a migration may be required.

When you first launch a version of OmniFocus that’s compatible with the new database format, or use Migrate Database…, you’ll see a Migration window which lists any clients that need to be updated to a later version, as well as which features will be enabled.

If you’re running a very old version of OmniFocus on a device that syncs with your current database, it may not be eligible for migration to the new database format. If this is the case, it will be indicated in the Migration window, and you’ll be asked to disconnect older versions. Choose Show Devices, then tap or click on Registered Devices, and Unregister those older versions before proceeding with the upgrade by re-selecting Migrate Database….

If you prefer to maintain sync compatibility with a very old version of OmniFocus, you can choose not to update to the new database format. However, newer features of OmniFocus that require the updated format will not be available on any devices that sync with that database.

When all of your devices with OmniFocus have versions that support the latest database format, the Migration window gives the green light to make the transition to the new, improved format. Choose Migrate Database, and OmniFocus will sync your database in the new format to all of your devices. If you choose Later, you’ll be prompted to migrate again in one day (and you can always use Migrate Database… to migrate sooner).

In the unlikely chance that something goes wrong during the migration process, OmniFocus automatically makes a backup that you can revert to, if needed.

Exporting From OmniFocus

Your OmniFocus data belongs to you. If you want to send it to other applications, run scripts on it, publish it on the web, or do other exciting stuff with it that we haven’t even thought of, you’re more than welcome to export it to the format of your liking.

Exporting on a Mac offers a variety of formats; exporting on iPhone or iPad offers the CSV format. If there is another export format you would find valuable on iPhone or iPad, please send us an email and let us know.

To export your data on iPhone or iPad, use Export to CSV in Data settings.

To export your data on a Mac, choose Export… from the File menu, and then choose a format and a location. The available formats are:

  • OmniFocus Document — This is an ordinary OmniFocus document, like the one that you use for your primary OmniFocus database. If you open this file in OmniFocus, it will appear in its own window, and you can work with it normally, including moving items into your primary OmniFocus database. Keep in mind that most settings are stored in and read from your primary database, rather than being pulled from the document that you are viewing, which can result in unexpected behavior.
  • Plain Text — This is a lightweight plain text version of your data, able to be opened in the text editor of your choice. OmniFocus’s plain text export is inspired by TaskPaper, the to-do list editor from Hog Bay Software. This export should be generally compatible with TaskPaper, and able to be imported with a minimum of fuss. See our OmniFocus TaskPaper Reference Guide support article for more information.
  • Simple HTML — This is a single-file HTML version of your data; the stylesheet and even the icons are embedded in the HTML. If you are proficient with CSS, you should be able to restyle the result however you like.
  • Comma Separated Values (CSV and CSV UTF-16) — CSV is an open syntax for applications old and new, on all platforms: all of your data in a plain text file with its columns separated by commas. Once you have your data in CSV format, it’s easy to run scripts on it, convert it to some other format, or open it in applications that understand it (like OmniPlan). If you’re having trouble persuading other applications to read the non-ASCII characters in your CSV file, such as accented letters or non-Roman characters, try exporting with the UTF–16 CSV option.
  • Backup Document (OmniFocus) — This export option creates a file in a format (.ofocus-backup) that is almost the same as the standard OmniFocus database format, with one key difference: unlike a standard OmniFocus database file, when you open a backup in OmniFocus, the option to Revert to This Backup appears right below the toolbar. Click this button to replace your primary OmniFocus data with the data contained in the backup. If you are syncing, this will also force all of your other devices to re-sync, bringing them all up to date.


Here are a few troubleshooting tips you can try, using OmniFocus’s built in self-help features.

Finding Misplaced Items

Have you lost track of something? Try these tips:

  • Use the Search Field (with the three options for Here, Remaining, and Everything).
  • Try using the Completed & Changed perspectives to track down missing actions or projects.
  • Check the Attachment List for images or other files that you may have attached to items tucked deep in your database.
  • Open an Archive of past OmniFocus work to look for items that may have been lost to time.

Improving Performance

Is OmniFocus a little slower than you’d like? Try these tips:

  • Sync all of your devices regularly! This reduces sync wait times and generally improves speed and performance across the board.
  • Compact your database to remove unneeded edit histories; if you are syncing, this will happen automatically, once all devices have synced the same information.
  • Archive projects that have been completed or dropped. Moving them to the Archive gives you a more streamlined database, while still being able to restore items in the future.
  • Delete unneeded attachments using the Attachment List, in order to lessen the sync load and storage space required for your OmniFocus data.
  • More information can also be found in our Troubleshooting OmniFocus Performance support article.

Sync Settings Reference

Account Name and Password

These fields allow you to enter the sync account name and password.

The account name cannot be changed while sync is turned on. To switch sync accounts, tap Turn Sync Off, then enter information for the new account.


Check whether your OmniFocus database is encrypted on the server, and optionally choose a separate passphrase (distinct from your sync password) for decrypting it. Learn more about OmniFocus encryption here.

Manage Your Omni Account

Opens a link to Omni Sync Server, where you can change your password, update your email address, enable Mail Drop, and access your sync server data.


Check the status of push-triggered sync on your sync account (it’s set to On by default). This feature offers faster, more frequent syncs; for more information, see this support article.

Registered Devices

View a list of devices registered to sync with your cloud database, along with some other useful information: the entry for your current device is highlighted in purple, and the day a device last synced is shown adjacent to it (if a device hasn’t synced in over a week, its last sync date is highlighted in yellow).

From the Registered Devices screen, you can also Edit the list to remove any devices you no longer want to sync with.

Replace Sync Data

Replace the OmniFocus data on the sync server with the data stored on your Mac, iPad, or iPhone. This can be used when you encounter a sync conflict, and you are sure that the local copy of your data is the one you want. This may also be a good time to check our online help or talk to our Support Humans.

Reveal Stored Password

View the password for your sync account as it is locally stored and encrypted on your device. This requires giving OmniFocus permission to reveal your secure data using Face ID or Touch ID, so another person accessing your device will not be able to see your password.

Sync Disabled

This setting isn’t recommended, but if you plan to use OmniFocus exclusively on your Mac, iPad, or iPhone, and syncing to a remote server is either not allowed or simply not desired, you can choose to leave OmniFocus’s sync features disabled. In all other cases, having a cloud-based copy of your data is a great way to rest at ease that your work won’t be lost if anything happens to the device you are using.

Sync Log

A sync log with a list of all your recent OmniFocus database sync activity, and the reasons for each sync event along with their durations. If anything seems strange here, you can copy the log for use when contacting Omni support.

View the timestamp for your last database sync at a glance here, or tap to view the log of all recent syncs and the reasons for them.

Syncing with an Omni Account

Omni maintains the Omni Sync Server, which is designed to work well with OmniFocus, while providing unique features like Mail Drop. We recommend this as the best sync solution for most users, since it’s the one for which we can provide the most support; it also happens to be free! If you have an Omni Account, you can use our sync service.

If you choose to entrust your data with the Omni Sync Server, we’ll treat it with utmost care and responsibility (see our Terms of Service and Privacy Policy). To set up sync with the Omni Sync Server, get started by creating a new Omni Account here.

Syncing With a WebDAV Server

Omni Sync Server is a great solution for most OmniFocus users, but if your sync needs require that your data be kept completely within a system you control, you can configure OmniFocus to sync using another WebDAV server.

Omni is not able to provide support for third party servers, so this option is not recommended unless you have a specific need for control over your own server, and you have the technical capability to administrate it. If you choose to go this route, OmniFocus sync is compatible with any WebDAV standards-compliant server, whether remote (there are many fine providers available) or hosted on your own Mac.

If data privacy is your primary concern when syncing, you may also wish to disable the Push feature in OmniFocus preferences (found in the Push row of Sync settings). Push registrations contain nothing specific to your database, but do represent information exchanged outside your server. See this support article to help determine whether push sync is right for your needs.

Cloud Storage and File Sharing

While services such as Dropbox, OneDrive, and Google Drive are great for file sharing, they don’t handle OmniFocus data properly. Using a file sharing service as a place to store your OmniFocus data can corrupt it. Please do not use file sharing services as a means of synchronizing your OmniFocus data, or non-iCloud Drive services for storing your OmniFocus data.

Turn Sync Off

Available on Mac
Available on iPhone and iPad

Turn off sync and use OmniFocus with a local database only. Leaving sync turned off is not recommended. If you need to switch sync accounts, tap this to turn off the currently connected account and use the setup dialog to connect to the new one.