How to Install Bottles on Ubuntu 26.04, 24.04 and 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, use the Flathub Flatpak, the upstream-documented desktop install path.

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, install the Flatpak package and add the Flathub remote before installing Bottles. 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 that work in a graphical interface that handles runners, dependencies, and per-application environments.

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. Bottles can also sit beside a separate system Wine install because its runners and prefixes live under its own Flatpak data directory.

The Bottles developers currently distribute the application through Flatpak. They do not provide an official Ubuntu APT package, PPA, Snap package, standalone .deb, or AppImage for normal desktop installs.

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, while AMD and Intel users can upgrade Mesa drivers on Ubuntu if games fail to launch or perform poorly with the default driver stack.

Install Bottles on Ubuntu with Flatpak

Use the Flathub package for Bottles on Ubuntu. The Flatpak application ID is com.usebottles.bottles, and the same install path works on Ubuntu 26.04, 24.04, and 22.04.

Install path	Current status	Use on Ubuntu
Flathub Flatpak	Upstream-documented desktop install path	Recommended for normal Bottles installs and updates
APT package or PPA	No official Ubuntu package or PPA from Bottles	Do not use `sudo apt install bottles` or old PPA instructions
Snap, `.deb`, AppImage, `.flatpakref`, or portable download	Not the supported Ubuntu desktop path	Use the Flathub remote so `flatpak update` keeps Bottles and its runtimes managed

Install Flatpak on Ubuntu

Install Flatpak if it is not already present on your system. Ubuntu does not include Flatpak by default, so update APT first:

sudo apt update

Commands in this article use sudo for tasks 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.

Install the Flatpak package from Ubuntu’s repositories:

sudo apt install flatpak -y

The -y flag automatically confirms the installation prompt. After installation, log out and back in so your desktop session sees Flatpak application launchers. A full reboot also works but is not required.

For detailed Flatpak setup and upgrade options, follow the guide to install Flatpak on Ubuntu.

Add the Flathub Repository

Add the Flathub repository to your system. Flathub is the remote that publishes Bottles and the runtimes it needs:

sudo flatpak remote-add --if-not-exists flathub https://dl.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.

Confirm that the flathub remote exists at system scope before installing Bottles:

flatpak remotes --columns=name,options | grep "^flathub"

Expected output:

flathub system

Install Bottles from Flathub

Install Bottles from the Flathub remote:

sudo flatpak install flathub com.usebottles.bottles -y

This command downloads Bottles and all required runtimes. The initial download may take several minutes because it includes the application, the GNOME runtime, Wine helper components, and graphics extensions.

Verify the Bottles Installation

Confirm Bottles installed correctly by checking its package information:

flatpak info com.usebottles.bottles

Relevant output includes:

          ID: com.usebottles.bottles
         Ref: app/com.usebottles.bottles/x86_64/stable
        Arch: x86_64
      Branch: stable
     Version: 63.2
      Origin: flathub
  Collection: org.flathub.Stable
Installation: system
     Runtime: org.gnome.Platform/x86_64/49

The exact version changes as Flathub publishes updates. The stable reference, system installation, and Flathub origin confirm that Ubuntu installed the intended Bottles 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, the onboarding wizard downloads the components needed to create bottles, including the Caffe runner, DXVK, and VKD3D. This one-time setup takes a few minutes depending on your internet connection.

Select a Bottles Environment Preset

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

Preset	Default behavior	Best For
Gaming	Enables DXVK and Esync by default; VKD3D can be enabled later for DirectX 12 titles	Windows games and game launchers
Application	Enables DXVK and VKD3D and adds common fonts plus Wine Mono	Office software, multimedia tools, utilities, and development apps
Custom	Starts from a minimal workspace where you choose the runner and components	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 applies the matching settings. Setup time varies based on your system, selected preset, and whether Bottles needs to download missing runners or compatibility components.

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 can run many Windows games on Linux through Wine runners and DirectX translation layers. The Gaming environment enables DXVK for DirectX 9, 10, and 11 titles by default; enable VKD3D in the bottle settings when a DirectX 12 game needs it.

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. Complete the first-run setup before using management commands such as list, new, or run; otherwise, Bottles may not have created its data directories yet.

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.

Relevant output includes:

usage: bottles-cli [-h] [-v] [-j] {info,list,programs,add,tools,reg,reg-rules,edit,new,run,standalone,shell} ...

List Your Bottles

Display all bottles you have created after the first-run setup has completed:

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. Use gaming for game launchers and DirectX 9, 10, or 11 titles, application for productivity and multimedia software, and custom when you want to choose the runner and graphics components yourself.

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.

Back Up Bottles Environments on Ubuntu

Bottles stores per-user data in ~/.var/app/com.usebottles.bottles/. The data/bottles/ subdirectory contains your individual Wine prefixes, including their virtual C: drives, registry data, installed Windows applications, and per-bottle configuration.

To transfer bottles to another Ubuntu machine, close Bottles, install the same Flathub package on the new system, then copy your saved data/bottles/ directory into the same Flatpak data path. For single environments, use Bottles’ built-in export or backup option when available so the app can package the bottle cleanly.

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 system-scope desktop entry exists:

ls /var/lib/flatpak/exports/share/applications/ | grep -i bottles

Expected output:

com.usebottles.bottles.desktop

Fix Bottles First Launch Download Failures

Bottles downloads the Caffe runner, DXVK, VKD3D, and related components on first launch. If these downloads fail, check your internet connection and firewall settings. Bottles fetches components from public project repositories 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:

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.
Search community discussions: Visit the Bottles Community Discussions on GitHub to find user-submitted configurations and troubleshooting tips for specific applications.

If the app still fails, check whether Bottles suggests dependencies after you select the executable. Recent Bottles builds can inspect Windows programs and recommend missing frameworks or runtimes from inside the bottle details view.

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 can 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 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 Mesa updates can include performance improvements and bug fixes. See our guide to upgrading Mesa drivers on Ubuntu if you encounter compatibility issues.

Also verify the graphics layer you need is enabled in your bottle’s settings. The Gaming preset enables DXVK by default, while DirectX 12 titles may need VKD3D enabled manually in Settings > Graphics.

Fix Bottles Runtime Not Installed Error

If Bottles fails to launch with a “runtime not installed” error, repair the Flatpak installation and update the app. Flatpak normally installs the required GNOME runtime automatically, so reinstalling a runtime by hand should be a last resort:

sudo flatpak repair --dry-run
sudo flatpak repair
sudo flatpak update com.usebottles.bottles -y

If the repair output still reports a missing runtime, reinstall Bottles from Flathub so Flatpak can resolve the current runtime branch again.

Fix Bottles File Access Permission Errors

Flatpak’s sandboxing restricts broad file access by default. Bottles already declares device access in its Flathub manifest, but Windows installers stored outside portal-selected locations may still need a filesystem override. Grant home-directory access for your user only when you need it:

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

The --user flag is intentional here because Flatpak stores this override in your account. To undo the change later, reset Bottles permissions:

flatpak override --user --reset com.usebottles.bottles

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:

sudo flatpak repair --dry-run
sudo flatpak repair
sudo flatpak update com.usebottles.bottles -y

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

Refresh Bottles, Flatpak runtimes, and related components with Flatpak’s update command:

sudo flatpak update -y

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 -y

Remove Bottles from Ubuntu

Remove Bottles while keeping your bottle environments and application data:

sudo flatpak remove com.usebottles.bottles -y

Remove Bottles and ask Flatpak to delete application data as part of the uninstall:

sudo flatpak remove --delete-data com.usebottles.bottles -y

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

sudo flatpak uninstall --unused -y

Flatpak stores user-specific application data separately from the system package. Bottles keeps its data in ~/.var/app/com.usebottles.bottles/, which contains your bottle environments, Wine prefixes, configurations, downloaded runners, and installed Windows applications. The user data directory can remain after --delete-data, so check it directly before assuming everything is gone.

Check whether the data directory still exists:

test -d "$HOME/.var/app/com.usebottles.bottles" && echo "DATA_DIR_PRESENT" || echo "DATA_DIR_ABSENT"

If the command prints DATA_DIR_PRESENT and you have already backed up anything important, delete the directory. The -rf flags force recursive deletion without confirmation prompts, so keep the path exact:

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

rm -rf "$HOME/.var/app/com.usebottles.bottles"

Verify Bottles has been removed from the system-scope Flatpak app list:

sudo flatpak list --app --columns=application | grep -Fx com.usebottles.bottles || echo "NOT_INSTALLED"

Expected output:

NOT_INSTALLED

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 Installation Documentation: Official installation notes for the Flatpak package.
Bottles Community Discussions: GitHub Discussions for community support, troubleshooting help, and sharing configurations.

Conclusion

Bottles is running on Ubuntu through Flathub, with isolated Wine environments for Windows applications, games, and test sandboxes. Keep it current through Flatpak updates, back up important bottles before removal, and use the runner and dependency tools when compatibility needs tuning. For adjacent Windows compatibility paths, see Install Wine on Ubuntu and Install Steam on Ubuntu.