How to Install Bottles on Ubuntu (26.04, 24.04, 22.04)

Bottles creates isolated Wine environments for running Windows applications on Ubuntu without dual-booting or virtual machines. Whether you need Windows productivity software for work, game launchers like Battle.net or EA App, or a clean testing sandbox for development, each “bottle” keeps its own dependencies, registry, and virtual filesystem separate from the rest of your system. To install Bottles on Ubuntu, you use Flatpak, the only distribution channel the Bottles developers officially support.

Unlike configuring Wine directly, Bottles handles runner management, dependency installation, and environment configuration through a graphical interface.

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 26.04, 24.04, and 22.04.

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 NVIDIA driver on Ubuntu (version 470+), while AMD and Intel users benefit from upgrading Mesa drivers on Ubuntu to version 21.0 or later.

Install Bottles on Ubuntu with Flatpak

Install Flatpak on Ubuntu

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

This guide uses sudo for commands that need root privileges. If your user is not in the sudoers file yet, follow the guide on how to add and manage sudo users on Ubuntu.

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 from Flathub

Download and install Bottles directly from the Flathub repository:

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 Bottles Installation

Confirm Bottles installed correctly by checking its package information:

flatpak info com.usebottles.bottles

Expected output:

Bottles - Run Windows software

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

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

Launch Bottles on Ubuntu

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), type “Bottles” in the search field, and click the Bottles application icon.

Create Your First Bottles Environment on Ubuntu

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 a Bottles Environment Preset

Click the + button or Create New Bottle to start. Bottles offers three environment presets:

Preset	Pre-installed Components	Best For
Gaming	DXVK (DirectX 9/10/11 to Vulkan), VKD3D (DirectX 12), gamemode integration	Windows games and game launchers
Application	General-purpose Wine configuration without gaming components	Office software, utilities, and development tools
Custom	None (minimal environment)	Advanced users who need specific runner and dependency 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 Bottles 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 with Bottles on Ubuntu

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 in Bottles

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 in Bottles

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.

Manage Bottles from the Command Line on Ubuntu

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 Bottles CLI Commands

Display all available bottles-cli subcommands:

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

This shows subcommands including info, list, programs, add, tools, reg, reg-rules, edit, new, run, standalone, 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 in Bottles

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 in Bottles

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 Bottles on Ubuntu

Fix 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/

Fix Bottles First Launch Download Failures

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.

Fix Bottles Application Compatibility Issues

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

1. Check dependencies: Many applications require Visual C++ redistributables or .NET Framework. Go to the Dependencies section and install the commonly needed packages.
2. Switch runners: Some applications work better with specific Wine versions. Try Wine-GE or Proton-GE from the Runners section.
3. Change Windows version: Some older applications require Windows 7 or XP compatibility. Adjust this in the bottle’s Settings section.
4. Enable virtual desktop: Applications that struggle with fullscreen mode often work better in virtual desktop mode, found in the Settings section.
5. Search community discussions: Visit the Bottles Community Discussions on GitHub to find user-submitted configurations and troubleshooting tips for specific applications.

Bottles 62 includes Eagle, an automated analysis tool that scans Windows executables to detect frameworks, runtimes, and potential compatibility issues. When you run an executable, Eagle examines the binary and suggests appropriate dependencies and settings. Look for the Eagle icon in the bottle details when running new software.

Fix Poor Gaming Performance in Bottles

Gaming performance in Bottles relies on Vulkan. DXVK translates DirectX 9/10/11 calls to Vulkan, and VKD3D handles DirectX 12. If Vulkan is not working correctly, games will fail to launch or run poorly.

Test whether Vulkan is functional on your system. The vulkaninfo command is part of the vulkan-tools package, which you can install with sudo apt install vulkan-tools if it is not present:

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

If this command fails or reports no devices, your graphics drivers either lack Vulkan support or need updating:

• NVIDIA users: The open-source nouveau driver has limited Vulkan support. Install the proprietary NVIDIA driver (version 470 or later recommended) for full Vulkan functionality. See our guide to installing NVIDIA drivers on Ubuntu for step-by-step instructions.
• AMD and Intel users: These GPUs use Mesa’s open-source Vulkan drivers. Ubuntu’s default Mesa version works for most games, but newer releases include performance improvements and bug fixes. See our guide to upgrading Mesa drivers on Ubuntu if you encounter compatibility issues.

Also verify DXVK is enabled in your bottle’s settings. The Gaming preset enables it by default, but Application and Custom presets do not. Enable DXVK manually in Settings → Graphics for any bottle where you want DirectX translation.

Fix Bottles 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.

Fix Bottles File Access Permission Errors

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.

Fix Bottles Crashes or Startup Failures

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 on Ubuntu

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 from Ubuntu

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. The -rf flags force recursive deletion without confirmation prompts, so verify the path before running:

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

Verify Bottles has been removed:

flatpak info com.usebottles.bottles

Expected output after removal:

error: com.usebottles.bottles is not installed

Frequently Asked Questions

Additional Resources

• Bottles Website: Project overview, features, download options, and release notes.
• Bottles GitHub Repository: Source code, issue tracker, and development activity.
• Bottles on Flathub: Flatpak package page with version history and sandbox permissions.
• Bottles Documentation: Official guides covering installation, configuration, troubleshooting, and advanced features.
• Bottles Community Discussions: GitHub Discussions for community support, troubleshooting help, and sharing configurations.

Conclusion

Bottles is running on Ubuntu with Flatpak, giving you isolated Wine environments for Windows applications without dual-booting or virtual machines. Flatpak delivers updates directly from Flathub, keeping runners and compatibility fixes current. Explore the dependency manager for Windows libraries your applications need, and experiment with different runners when compatibility requires fine-tuning. For more ways to run Windows software, see our guides on installing Wine on Ubuntu and installing Steam on Ubuntu.