How to Install Bottles on Ubuntu

Bottles provides a modern, user-friendly way to run Windows applications on Ubuntu without dual-booting or virtual machines. Whether you need to run Windows productivity software for work, play games through Battle.net or EA Launcher, or test Windows applications during development, Bottles creates isolated Wine environments that keep each application’s dependencies separate and manageable.

Unlike configuring Wine directly, Bottles handles runner management, dependency installation, and environment configuration through an intuitive graphical interface. This guide walks you through installing Bottles via Flatpak on Ubuntu, setting up your first environment, and managing the application.

Flatpak is not pre-installed on Ubuntu. If you have not set it up yet, this guide includes the necessary installation steps. Flatpak provides universal package compatibility across all Ubuntu LTS releases, so the commands work identically on Ubuntu 22.04, 24.04, and 26.04.

Contents hide

1 What Is Bottles?

2 Install Bottles with Flatpak

3 Launch Bottles

4 Create Your First Environment

5 Run Windows Games

6 Use Bottles from the Command Line

7 Troubleshoot Common Issues

8 Update Bottles

9 Remove Bottles

10 Conclusion

11 Additional Resources

What Is Bottles?

Bottles builds on Wine, the compatibility layer that translates Windows API calls to Linux equivalents. Wine alone requires manual configuration of environment variables, dependencies, and version management. Bottles wraps this complexity in a graphical interface that handles the technical details automatically.

Each “bottle” is an isolated Wine prefix with its own virtual Windows filesystem, registry, and installed applications. This isolation means software in one bottle cannot interfere with another, and you can configure different Wine runners, Windows versions, and dependencies for each environment without conflict.

The Bottles developers distribute their application exclusively through Flatpak. They do not provide APT packages, PPAs, or Snap packages because Flatpak’s sandboxing model aligns with their architecture for managing Windows compatibility layers.

Gaming performance in Bottles depends on your GPU’s Vulkan support. DXVK and VKD3D translate DirectX to Vulkan and require a Vulkan-capable graphics driver. NVIDIA users should install the proprietary driver (version 470+), while AMD and Intel users benefit from Mesa 21.0 or later.

Install Bottles with Flatpak

Install Flatpak

Install Flatpak if it is not already present on your system. Ubuntu does not include Flatpak by default:

sudo apt update && sudo apt install flatpak -y

The -y flag automatically confirms the installation prompt. After installation, log out and back in to ensure XDG integration takes effect. A full reboot also works but is not required. If you skip this step, you may encounter missing application icons or desktop menu entries.

For detailed Flatpak configuration options, including setting up Flathub during installation or upgrading to newer versions, refer to our guide to installing Flatpak on Ubuntu.

Add the Flathub Repository

Add the Flathub repository to your system. Flathub is the primary source for Flatpak applications, including Bottles and many other applications not available in Ubuntu’s default repositories:

sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

The --if-not-exists flag prevents errors if Flathub is already configured. This command adds Flathub at system scope, making applications available to all users on the machine.

Install Bottles

Install Bottles from Flathub:

sudo flatpak install flathub com.usebottles.bottles -y

This command downloads Bottles and all required runtimes. The initial download may take several minutes depending on your internet connection, as it includes the application, the GNOME runtime, and supporting libraries.

Verify the Installation

Confirm Bottles installed correctly by checking its package information:

flatpak info com.usebottles.bottles

Expected output:

Bottles - Run Windows in a Bottle

          ID: com.usebottles.bottles
         Ref: app/com.usebottles.bottles/x86_64/stable
        Arch: x86_64
      Branch: stable
      Origin: flathub
     Version: 60
     License: GPL-3.0-only

The version number, architecture, and Flathub origin confirm you have the official package.

Launch Bottles

Launch Bottles from the terminal or the applications menu. Terminal launching is useful for troubleshooting, as errors and warnings appear in the terminal output:

flatpak run com.usebottles.bottles

To launch from the graphical interface, open the Activities overview (click Activities in the top-left corner or press the Super key), type “Bottles” in the search field, and click the Bottles application icon.

Create Your First Environment

When you first launch Bottles, it downloads essential components including Wine runners and DXVK. This one-time setup takes a few minutes depending on your internet connection. The progress appears in the Bottles interface, and you can create environments once the downloads complete.

Select an Environment Preset

Click the + button or Create New Bottle to start. Bottles offers three environment presets, each configured for different use cases:

Gaming

Pre-installs DXVK for DirectX 9/10/11 translation to Vulkan
Includes VKD3D for DirectX 12 support
Configures performance optimizations like gamemode integration
Best for Windows games and game launchers

Application

General-purpose environment for productivity software
Lighter configuration without gaming-specific components
Suitable for office software, utilities, and development tools

Custom

Minimal environment with no pre-installed components
Full control over runner selection and dependencies
For advanced users who need specific configurations

Name your environment descriptively. For example, use “Work Apps” for office software or “Blizzard Games” for Battle.net. Clear naming helps when managing multiple bottles.

After selecting a preset, Bottles creates the Windows environment and installs necessary dependencies. The Gaming preset downloads DXVK for DirectX translation along with various Windows runtime libraries. Setup time varies based on your system and preset selection, ranging from under a minute for Custom to several minutes for Gaming.

Configure Environment Settings

The bottle details screen appears after creation completes. This screen provides access to all configuration options:

Run Executable: Launch Windows .exe files directly by browsing to them.
Manage Dependencies: Install Windows libraries like .NET Framework, Visual C++ redistributables, or DirectX runtimes from a curated list.
Switch Runners: Change between Wine versions, Wine-GE, Proton-GE, or other community runners. Different runners can improve compatibility with specific applications.
Adjust Settings: Configure display resolution, virtual desktop mode, DXVK/VKD3D versions, Windows version emulation, and environment variables.

Run Windows Games

Bottles excels at running Windows games on Linux. The Gaming environment preset comes pre-configured with DXVK, VKD3D, and performance optimizations that handle most games without additional configuration.

Install Gaming Launchers

Bottles includes built-in installers for popular gaming platforms. Navigate to the Installers tab in your Gaming bottle to find one-click installers for:

Battle.net (Blizzard games including Diablo, StarCraft, and Overwatch)
EA App (formerly Origin)
Epic Games Launcher
GOG Galaxy
Ubisoft Connect

Select a launcher and click Install. Bottles downloads the official installer and runs it within the environment, handling dependency installation automatically. The launcher appears in your bottle’s Programs section.

Launch Installed Games

After installing a gaming platform, launch it from the Programs section of your bottle. Bottles automatically detects installed programs and creates launch entries. You can create desktop shortcuts for frequently used applications by right-clicking a program entry and selecting the shortcut option.

For native Linux gaming through Steam with Proton support, see our guide to installing Steam on Ubuntu. Steam’s built-in Proton handles many Windows games automatically. If you prefer working with Wine directly for greater control, our Wine installation guide for Ubuntu covers manual configuration.

Use Bottles from the Command Line

Bottles includes a command-line interface for automation, scripting, or managing bottles without opening the GUI. These commands are useful for power users who want to integrate Bottles into scripts or prefer terminal workflows.

View Available CLI Commands

Display all available bottles-cli subcommands:

flatpak run --command=bottles-cli com.usebottles.bottles --help

This shows subcommands including info, list, programs, tools, reg, edit, new, run, and shell.

List Your Bottles

Display all bottles you have created:

flatpak run --command=bottles-cli com.usebottles.bottles list bottles

Create a Bottle from Terminal

Create a new bottle without opening the GUI:

flatpak run --command=bottles-cli com.usebottles.bottles new --bottle-name MyApps --environment application

The --environment flag accepts gaming, application, or custom. Gaming bottles include DXVK and performance optimizations, while application bottles use conservative settings for productivity software.

Run a Windows Executable

Launch a Windows program in a specific bottle:

flatpak run --command=bottles-cli com.usebottles.bottles run -b MyApps -e /path/to/program.exe

Replace MyApps with your bottle name and provide the full path to the Windows executable.

Launch Wine Tools

Access Wine utilities like winecfg, regedit, or taskmgr within a bottle:

flatpak run --command=bottles-cli com.usebottles.bottles tools -b MyApps winecfg

Available tools include cmd, winecfg, uninstaller, regedit, taskmgr, control, and explorer.

Troubleshoot Common Issues

Bottles Not Appearing in Applications Menu

If Bottles does not appear in your applications menu after installation, Flatpak’s XDG integration may not have activated. Log out and back in, or reboot your system. Verify the desktop entry exists:

ls ~/.local/share/flatpak/exports/share/applications/ /var/lib/flatpak/exports/share/applications/ 2>/dev/null | grep -i bottles

If the file exists but the icon is missing from menus, refresh the desktop database:

update-desktop-database ~/.local/share/applications/

First Launch Downloads Fail

Bottles downloads Wine runners and DXVK components on first launch. If these downloads fail, check your internet connection and firewall settings. Bottles fetches components from GitHub releases and other external sources that may be blocked on some networks.

If downloads stall repeatedly, launch Bottles from the terminal to see detailed error messages:

flatpak run com.usebottles.bottles

Watch for connection errors or timeout messages that indicate network issues.

Application Not Running Correctly

Compatibility issues vary by application. Try these steps in order:

Check dependencies: Many applications require Visual C++ redistributables or .NET Framework. Go to the Dependencies section and install the commonly needed packages.
Switch runners: Some applications work better with specific Wine versions. Try Wine-GE or Proton-GE from the Runners section.
Change Windows version: Some older applications require Windows 7 or XP compatibility. Adjust this in the bottle’s Settings section.
Enable virtual desktop: Applications that struggle with fullscreen mode often work better in virtual desktop mode, found in the Settings section.
Check the compatibility database: Visit the Bottles Database to see if other users have reported settings that work for your application.

Poor Gaming Performance

Ensure your graphics drivers support Vulkan. DXVK translates DirectX to Vulkan, so Vulkan must work correctly:

vulkaninfo --summary 2>/dev/null | head -20

If this command fails or shows no devices, install or update your graphics drivers. NVIDIA users need the proprietary driver, while AMD and Intel users should update Mesa.

Verify DXVK is enabled in your bottle’s settings. The Gaming preset enables it by default, but Application and Custom presets do not.

Runtime Not Installed Error

If Bottles fails to launch with a “runtime not installed” error, a required Flatpak runtime is missing. Install the missing runtime and update:

flatpak install flathub org.gnome.Platform
flatpak update

The error message specifies which runtime version is needed. Adjust the command if the error mentions a specific version number.

Permission Errors with File Access

Flatpak’s sandboxing restricts file access by default. If Bottles cannot access files on your system, grant permission to your home directory:

flatpak override --user com.usebottles.bottles --filesystem=home

For more granular control, install Flatseal from Flathub. This GUI application manages Flatpak permissions and provides checkboxes for common access patterns.

Bottles Crashes or Fails to Start

If Bottles worked previously but now crashes or fails to start, try repairing the Flatpak installation:

flatpak repair
flatpak update

If the issue persists, check available disk space. Bottles and its Wine prefixes require significant storage:

df -h ~

Each bottle can consume several gigabytes depending on installed applications and dependencies.

Update Bottles

Keep Bottles current with the latest features and security fixes:

sudo flatpak update

This command checks for updates to all installed Flatpak applications, including Bottles and its runtimes. Review the listed updates and confirm when prompted. GNOME Software and other graphical package managers also notify you of available Flatpak updates.

To update only Bottles:

sudo flatpak update com.usebottles.bottles

Remove Bottles

Remove Bottles while keeping your bottle environments and application data:

sudo flatpak uninstall com.usebottles.bottles

Remove Bottles along with its Flatpak application data:

sudo flatpak uninstall --delete-data com.usebottles.bottles

Clean up unused Flatpak runtimes that were only needed by Bottles:

sudo flatpak uninstall --unused

Flatpak stores user-specific application data separately from the package. Bottles keeps its data in ~/.var/app/com.usebottles.bottles/, which contains your bottle environments, Wine prefixes, configurations, and installed Windows applications.

The following command permanently deletes all Bottles data, including your bottle environments, installed Windows applications, and associated settings. Back up any important data before proceeding.

Delete the data directory to completely remove all traces of Bottles:

rm -rf ~/.var/app/com.usebottles.bottles/

Conclusion

Bottles provides a straightforward way to run Windows applications on Ubuntu through isolated Wine environments. Flatpak handles installation and updates, delivering the latest features directly from the developers. The Gaming preset streamlines setup for Windows games with pre-configured DXVK and VKD3D, while the Application environment handles productivity software with minimal overhead. Use the dependency manager to add Windows libraries when applications require them, and explore alternative runners when compatibility requires fine-tuning.

Additional Resources

Bottles Website: Project overview, features, and download information.
Bottles GitHub Repository: Source code, issue tracker, and development activity.
Bottles on Flathub: Flatpak package page with version history and permissions.
Bottles Documentation: Guides covering configuration, troubleshooting, and advanced usage.
Bottles App Store: Community-maintained installers for popular Windows applications.
Bottles Database: Application compatibility database with user-submitted reports and configuration tips.
Bottles Community Discussions: GitHub Discussions for community support and troubleshooting help.