Introduction

CrossOver allows you to run Windows software on your Mac. Because CrossOver integrates the applications with macOS, games like Grand Theft Auto V, Elder Scrolls V: Skyrim Special Edition, and The Witcher 3: The Wild Hunt, or productivity apps like Quicken launch like any native program. It's as simple as a double-click.

Installing CrossOver

1. Download the CrossOver installer from the CodeWeavers website.
2. Locate the file in Finder (usually in your Downloads folder).
3. Double-click to extract the zip file.
   
4. Double-click CrossOver to launch. When prompted, select Move to Applications Folder to install in Applications, or select Do Not Move to keep CrossOver in the current folder. If you don't want to see this prompt in the future, check Don't ask again. Our recommendation is to move to Applications.

Note: You can also drag and drop CrossOver to install it anywhere on your system. However, CrossOver is only available to all users on a machine when installed in the Applications folder.

Registering CrossOver

If you haven’t registered CrossOver it will start in trial mode. To continue using CrossOver in trial mode, click Try Now. The CrossOver trial has all the functionality of the full version. However, after 14 days, installed Windows applications are disabled. CrossOver periodically prompts you to register before the trial period ends.

Clicking Buy opens the CodeWeavers store. If you have already purchased CrossOver, click Unlock with Purchase Info.

Unlocking with Email and Password

After startup, you can unlock CrossOver by going to CrossOver > Unlock CrossOver.

Enter the email address and password associated with your codeweavers.com account in the CrossOver Trial dialog box and click Unlock.

Note: If unlocking for all users, you need your Mac username and password.

Unlocking with an Activation Code

If you purchased CrossOver from codeweavers.com, an activation code is not needed to register.

However, if you bought CrossOver from a third party and received an activation code, click Enter an Activation Code on the CrossOver Trial dialog box.

To complete the Enter Activation Code form you will need to enter either your existing codeweavers.com account information, or your email address and a new password to create a codeweavers.com account.

Installing Windows Applications

CrossOver installs Windows applications into bottles. A bottle is a virtual Windows environment (e.g., Windows XP or Windows 10) with its own C: drive, fonts, registry, and software. You can install multiple programs into a bottle, but generally, CrossOver creates a new bottle for each application.

Keeping applications in separate bottles prevents them from interacting with or damaging one another. For instance, you could test out a new version of a particular program in one bottle while keeping your original one in another. Multiple bottles are also helpful whenever a specific application requires otherwise undesirable settings.

Applications generally fall into two categories:

Listed — A listed application is an application that appears in CrossOver's application database. CrossOver determines as many install details as possible.

Unlisted — An unlisted application is an application that does not appear in CrossOver's application database. CrossOver does not default any install details for unlisted applications.

Listed Applications

Type the application name in the search bar on the Install menu. CrossOver populates a list of applications matching the search criteria.

Click the application's tile to proceed to the install details. If the application is not listed, see the next section on installing an unlisted application.

Install Details

CrossOver automatically downloads the installer file and the required dependencies if an application is freely available on the internet. No further action is needed to configure your application once each install detail has a check mark. Click Install to proceed.

Editing Install Details

If CrossOver cannot obtain an installer file because it is unavailable for download or requires login credentials, you must provide the installer file location.

Click Edit to access your file system.

1. Navigate to the location of the installer file.
2. Select the file and click Choose Installer.
3. When CrossOver displays a check mark for each detail, click Install.

Note: You can also use the Edit buttons to override the default selections. Even when CrossOver downloads an installer automatically, you can click Edit to select a different installer that you have downloaded to your machine. You can also click the Edit button next to the bottle information if you wish to install your application into a different bottle type from the one CrossOver automatically selected.

Advanced Options

To access additional install options, click the dropdown menu to the right of Install and select Advanced Options.

Create log file - To create a debug log during installation of a Windows application, select Create log file. The Wine logging channels field is automatically populated with some of most useful logging channels. You can also manually enter different ones or click the plus sign to select channels from the menu. If you want to change the save location for the log file, click Change to select a new save location. Click Done to return to the Install screen.

Application language - If more than one language is available for an application, you can use the dropdown menu to change the language.

Items to install - Some Windows applications require the installation of additional dependencies to run well with CrossOver. Many of our install profiles select the required dependencies automatically. You can also add dependencies to install by clicking the + icon. To remove dependencies that CrossOver added, click the - icon next to the dependency name. To undo any changes, click Revert. Click Done to return to the Install screen.

Completing the Install

During installation, Windows software may prompt you for input (e.g., language selection, end-user license agreements). If you believe the install has frozen, look for dialog boxes from the Windows program before clicking Cancel in CrossOver. Canceling the install can result in an unrecoverable problem that requires you to delete the target bottle.

The program you are installing may require input to complete the setup. For example, when Notepad++ is finished installing, you must click Finish.

Once the application is installed, CrossOver creates an icon on the Home screen and in the bottle made for the application.

Unlisted Applications

Unlisted applications may not run correctly or at all. Therefore we recommend installing unlisted applications in a separate bottle. Installing an unlisted application into an existing bottle may cause other Windows applications in that bottle to behave incorrectly.

To install an unlisted application, from the Install screen, do the following:

1. Click Install an unlisted application.
2. Click Edit for installer file detail.
3. Navigate to the installer file location.
4. Select the installer file and click Choose Installer.
5.  Click Edit for the bottle install detail.
6. Enter a name for the bottle in New Bottle Name.
7. Select a bottle type from the New Bottle Type menu.
   

Note: If you have difficulty installing an unlisted application, check the CrossOver Compatibility Center.

Applications without installers

Some Windows applications have standalone executables (.exe) that can be run without being installed. These programs can also be run with CrossOver.

1. From the main menu, go to Bottle > New Bottle. Enter a name for the bottle, select a bottle type, and click Create.
    
2. Select the bottle you just created in the left sidebar, then drag and drop the .exe you want to run into the bottle. Taking this action will open Run Command, and you can simply click Run to launch your application.
   
3. To make it easier in the future to run the application, you can click Save Command as a Launcher. This creates a launcher icon for the selected executable in your bottle. If the executable is moved or deleted, this launcher icon will stop working. Make sure the executable is saved somewhere that won’t change.
   

Running Windows Applications

To launch a Windows application from CrossOver, double-click the application icon. You can do this from the individual bottle view or the Home view.

The Home view displays icons for all installed Windows applications. This view can be customized to show only the icons that you want to see. To remove an icon, right-click and select Hide from Home.

Hiding an icon from the main menu does not delete the application from your disk or impact desktop integration.

To restore a hidden icon to your Home, select the bottle, right-click the icon and choose Show in Home.

Launchpad and Dock

When you install a Windows application, CrossOver creates an application icon in your Launchpad. Locate the Windows application icon in Launchpad and launch the program by double-clicking. You can also drag the Windows application icon from Launchpad, or from CrossOver's main window, to your Dock for easier access.

Note that when you launch a Windows application CrossOver will also open.

Working with Bottles

CrossOver installs Windows applications into bottles. A bottle contains a C: drive and all its standard folders (e.g., Windows and Program Files), as well as:

• A Windows registry.
• CrossOver settings.
• One or more Windows applications.
• Saved user data.

Unless you specify otherwise, CrossOver installs each application into a new bottle.

Multiple bottles are helpful when a particular application requires otherwise undesirable system settings. It is also possible to maintain bottles that emulate different Windows versions. For instance, an older application may run best in a Windows XP bottle, while a more modern one requires a Windows 10 bottle.

Bottle View

When a bottle is selected, CrossOver displays the Run with Options and Run Command buttons, and the Bottle Actions, Advanced Settings, Control Panels, and Bottle Details menus in the right sidebar.

Run Command — Access a Windows command prompt in CrossOver to run standard Wine tools (e.g., regedit or notepad) or applications without icons or shortcuts. Click Browse to access the contents of the bottle’s C: drive. You may need to hunt around to find the correct file. An excellent place to start your search is in Program Files. Once you have located and selected the .exe file, click Run.

If you need to run the same command regularly, create a shortcut for it by clicking Save Command as Launcher.

• Run with Options — When an application's icon is selected from a bottle, CrossOver displays Run with Options in the sidebar. Running an application with options is for collecting debug logs, and adding command-line options or environment variables. To enable logging, select Create log file. The Wine logging channels field is automatically populated with some of most useful logging channels. You can also manually enter different ones or click the plus sign to select channels from the menu. If you want to change the save location for the log file, click Change to select a new save location. Click Run to launch the application with logging enabled. Repeat the actions that triggered the original issue in the Windows program. When finished, close the Windows application and the CrossOver Run with Options dialog box.

Bottle Actions

Helpful shortcuts that allow you to manage a bottle's environment in CrossOver.

• Open C: Drive — Open the contents of the selected bottle's C: drive in the file manager.

• Install Applications Into Bottle — Install an application into the selected bottle. This option brings you to the Install menu. After selecting an application, the selected bottle will be the default install target.

Quit All Applications — Close all applications in the selected bottle. If an application is unstable or not responding and quitting the bottle fails, selecting Quit All Applications stops all processes still running inside the bottle. This may result in lost work if you have unsaved changes. If quitting is not successful, Quit All Applications becomes Force Quit instead.

Delete Bottle — Permanently delete the selected bottle. This action cannot be undone.

Advanced Settings

D3DMetal - D3DMetal is a graphics API translation layer from the game porting toolkit supporting DirectX 11 and DirectX 12 games. When enabled, D3DMetal is used instead of DXVK or the wined3d default.

DXVK — DXVK is a Vulkan-based translation layer for Direct3D 10 and 11. When enabled, DXVK is used instead of the wined3d default. Some games run better with DXVK, while others run better with wined3d.

ESync — Eventfd-based synchronization. Some applications run with better performance with ESync enabled, some applications show no difference, and some applications are broken by ESync.

MSync — Mach semaphore-based synchronization. Some applications run with better performance with MSync enabled, some applications show no difference, and some applications are broken by MSync.

High-Resolution Mode — High-resolution mode switch. When enabled in CrossOver Mac, pixel doubling is turned off, and CrossOver reports a high-resolution (192 DPI) to the application. If the application handles this correctly, graphics display in more detail. Not all applications render correctly in high-resolution mode.

Control Panels

In addition to the tools installed along with Windows applications, CrossOver provides several built-in control panel tools.

System settings should be changed using the configuration tools available on your system because most Windows control panels are unsupported and often don't work as designed.

Wine Configuration — Access a range of bottle configuration settings applicable when troubleshooting system integration issues.

Game Controllers — Game controller or joystick configuration.

Simulate Reboot — Replicates a Windows reboot for the selected bottle.

Task Manager — Display a list of processes running in the selected bottle. The task manager is helpful when you need to stop specific unresponsive processes.

Internet Settings — Network configuration.

Bottle Details

Shows a list of Windows applications and components in a bottle. There is also a Description field where you can enter notes specific to this bottle.

To uninstall an application from a bottle, right-click on name of the application in the list and select Uninstall. Follow the Windows prompts to uninstall the application.

Note: This action is irreversible. If you delete an application that another application depends on, your entire bottle could stop working.

Bottle Commands via Main Menu

Additional bottle commands are available in the Bottle submenu via CrossOver's menu bar.

New Bottle — Creates an empty bottle and allows you to choose the Windows version of the bottle.

Duplicate Bottle — Creates an exact copy of the bottle. You can select a new name for the duplicate bottle before it is created.

Rename Bottle — Makes the bottle name field editable so a bottle can be renamed.

Export Bottle to Archive — Create a compressed copy of the selected bottle. Select a name and save location for the archive and click Save. The bottle status will change to archiving while the archive is being created, and the bottle will be unusable until the archive is complete. We recommend creating a bottle archive before installing new software or modifying bottle settings in case you need to revert the bottle to a previous state. Bottle archives can also be used to move a bottle to a new machine.

• Import Bottle Archive — Restore an archived bottle. Navigate to the location of the .cxarchive file you want to restore, select it and click Restore. Your imported bottle will appear in the left sidebar.

Publish Bottle — Publish a copy of the selected bottle. This allows all users of your system have access to the bottle’s applications and data. Bottles are private when first created. Private bottles are accessible only to the user who created them via that user's home folder.

Note: CrossOver stores published bottles in a public directory (~/CrossOver.app/Contents/SharedSupport/CrossOver).

Update Published Bottle — Update a published bottle. Changes made to a published bottle are unavailable to other users until the published bottle is updated.

Open Shell — Launches a terminal that changes the directory to the C: drive of the selected bottle and sets the required environment variables for Wine to function. To access the Windows command prompt, enter wine cmd. To run a Windows application, enter wine --cx-app executable.exe, substituting in the name of the executable to run. Note that these are advanced options that may or may not work well, depending on your desired use case.

Preferences

CrossOver preferences are available from the CrossOver > Preferences menu. These settings modify the behavior of CrossOver as a whole, affecting all bottles uniformly.

Preferences are stored separately for each user. Therefore, changing your preferences does not impact other users on your Mac.

Online Integration

Check for CrossOver Updates — Occasionally, between major releases, CrossOver is updated. Select this option and CrossOver automatically checks for updates.

Remind About Submitting Ratings — When enabled, CrossOver reminds you to submit ratings for installed applications. Ratings help us improve future versions of CrossOver and inform other users how well applications work with CrossOver.

System Integration

Bottle Folder – CrossOver stores bottles in the folder shown here. To change the folder, click the folder and choose a new location. Be careful changing this to a folder on a folder on an external drive: using a different filesystem can result in broken bottles. To revert back to the default location, click Reset.

Program Folder – CrossOver creates icons for installed applications in the folder shown here. To change the folder, click the folder and choose a new location. To revert back to the default location, click Reset.

Installer Assistant

Automatically Download New Installation Recipes — CodeWeavers staff and volunteers are constantly updating, refining, and adding to the list of community-supported applications via the CodeWeavers CrossOver Compatibility Center. When enabled, CrossOver periodically synchronizes itself with that list of applications. Disabling this feature does not prevent you from installing applications via the website.

Hide Entries for Untested and Known-Not-To-Work Software — By default, CrossOver will display entries for all applications. You can check this box to hide all one-star, two-star, and unrated applications.

Launch Installer Assistant — When this option is selected double-clicking an .exe file will startup CrossOver and begin a new software install. When unchecked CrossOver will try to run the .exe program directly using an existing bottle.

Cache of Downloaded Installers — When CrossOver obtains an installer file during the install process, it keeps a copy of that file for future installs. If you need free disk space or are experiencing issues reinstalling software, click Clear to remove cached files.

Troubleshooting

Clear and Rebuild Programs

This command recreates the Windows application icons that CrossOver generates when a program is installed. If you are trying to launch your Windows application from its icon in Launchpad or the Dock and nothing happens, use this menu option and see if the regenerated Windows application icon works again.

Repair Bottles

Antivirus software can incorrectly flag and delete CrossOver files, which results in CrossOver not working correctly. This command will rescan your bottles and attempt to repair the files that the antivirus program corrupted.

More details on how to prevent your antivirus software from mistakenly flagging CrossOver can be found be found by clicking the Learn More button or at this support article.

Check For Updates

CrossOver automatically checks for updates on launch, but you can also manually check for new releases from the CrossOver > Check For Updates menu. If a new update is available CrossOver will download it, apply the changes, and reopen. If there is an update available, but your license has expired, you will be prompted to visit the CodeWeavers store to renew.

CrossOver Support

If you need further assistance please search our support library, search our Compatibility Center, or contact our technical support team.

CrossOver is a trademark of CodeWeavers, Inc. Linux is a registered trademark of Linus Torvalds. Windows is a registered trademark of Microsoft Corporation. All other trademarks and registered trademarks are owned by their respective companies.