Sooner or later, almost every Ubuntu user hits the same wall. A client sends an installer that only exists for Windows. A accounting tool, a CAD viewer, or an old game never got a Linux build. Dual booting feels heavy, and a full virtual machine eats RAM you would rather keep for real work.
That is where Bottles earns its place. It wraps Wine in a tidy graphical manager, keeps every application in its own isolated prefix, and handles the dependency installs (fonts, runtimes, DXVK and friends) that used to mean an evening of forum digging. Ubuntu 26.04 LTS, codenamed Resolute Raccoon, shipped on April 23, 2026 with five years of standard support, so it is a sensible base to build a long-lived Windows-compatibility setup on. It runs Linux 7.0 and GNOME 50 on Wayland.
There is one catch worth knowing before typing a single command. Bottles is not something to pull from random PPAs or old .deb files. The developers recommend Flatpak as the way to install it, because that is the only fully sandboxed build and it bundles the dependencies Bottles needs. Most of the problems seen on forums come from skipping that advice.
This guide covers the full path. You will set up Flatpak, install Bottles, create your first bottle, tune it for performance, lock down permissions, and fix the errors that tend to appear on fresh installs.
What Bottles Actually Is (and Why It Beats Plain Wine)
Bottles is a manager, not a Windows emulator. Underneath it still uses Wine (or Proton-based forks), which translates Windows API calls to Linux ones at runtime. What Bottles adds is organization.
Each “bottle” is a separate Wine prefix with its own registry, its own installed libraries, and its own settings. If one application breaks, nothing else does. That isolation is the real selling point. Anyone who has used a single shared ~/.wine directory for five years knows what a corrupted prefix feels like.
Bottles ships three starting environments.
- Gaming enables DXVK, VKD3D, and sensible graphics settings.
- Software is tuned for office tools, utilities, and business apps.
- Custom gives a blank prefix for people who want to assemble everything manually.
It also supports multiple runners, meaning different Wine builds. That matters more than it sounds. Some programs run fine on stock Wine and break on a newer build, and swapping the runner takes two clicks instead of a reinstall.
Before You Start: System Checks
Spend two minutes on prerequisites. It saves an hour later.
Confirm the Ubuntu release and architecture
lsb_release -a
uname -mYou should see Ubuntu 26.04 and x86_64. Bottles targets x86 and x86_64 Windows software, so ARM machines need a different approach (translation layers) and are outside this guide.
Update the system first
sudo apt update
sudo apt upgrade -yOn a production-style workstation, reboot if a new kernel was installed. Running a graphics stack on a half-updated system produces confusing errors that look like Bottles bugs.
Check your graphics drivers
Windows games and many apps lean on Vulkan. Verify it works before blaming Bottles.
sudo apt install -y vulkan-tools mesa-vulkan-drivers
vulkaninfo --summaryIf vulkaninfo lists your GPU, you are good. On NVIDIA hardware, install the proprietary driver through “Additional Drivers” or with:
sudo ubuntu-drivers devices
sudo ubuntu-drivers installReboot afterward. An empty Vulkan device list is the single most common reason a Bottles gaming profile runs at slideshow speed, because the app silently falls back to software rendering.
Disk space and RAM
Plan for at least 10 GB free for Bottles, runtimes, and a couple of bottles. Every bottle carries its own copy of libraries, so five bottles can easily reach 15 to 20 GB before any application data. 8 GB of RAM is comfortable for office software. For modern games, 16 GB is the practical floor.
Installing Bottles on Ubuntu 26.04 LTS with Flatpak
This is the recommended method and the one that holds up best over time.
Step 1: Install Flatpak
Ubuntu does not ship Flatpak by default, since Canonical pushes Snap. Installing it is trivial.
sudo apt install -y flatpakIf you use the GNOME desktop and want Bottles to show up in the software center, add the plugin too:
sudo apt install -y gnome-software-plugin-flatpakStep 2: Add the Flathub repository
sudo flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepoFlathub is where Bottles is published. The --if-not-exists flag makes the command safe to repeat, which is handy in provisioning scripts.
Step 3: Restart your session
Flatpak adds export paths for menu entries and environment variables. Log out and back in, or reboot. Skipping this is why people install Bottles and then cannot find the launcher.
Step 4: Install Bottles
flatpak install flathub com.usebottles.bottlesPress Y when asked. The first install pulls a GNOME runtime and several extensions, so expect a download well beyond the size of Bottles itself. Subsequent Flatpak apps reuse those runtimes.
A system-wide install (with sudo) makes the app available to all users, while a per-user install keeps everything inside the home directory. For a shared workstation, system-wide is cleaner. For a personal laptop, per-user avoids needing root:
flatpak install --user flathub com.usebottles.bottlesPick one style and stay with it. Mixing system and user installs of the same app leads to confusing duplicate entries.
Step 5: Launch and verify
flatpak run com.usebottles.bottlesOr open it from the application grid. To confirm the source and version:
flatpak info com.usebottles.bottlesThe first launch runs a short onboarding that downloads a default runner and runtime components. Let it finish. Closing it halfway is a classic way to end up with a broken setup that later needs a manual reset.
Alternative Installation Methods (and Why They Are Second Choice)
Beta channel via Flathub Beta
The Bottles documentation lists a beta remote for people who want newer builds.
flatpak remote-add --user flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo
flatpak update --appstream
flatpak install --user flathub-beta com.usebottles.bottlesIt is fine for testing on a spare machine. Keep the stable branch on anything you depend on for work.
Building from source
The docs also describe a manual build with flatpak-builder, which requires the GNOME SDK and 32-bit compatibility extensions. Do this only if you are contributing patches or debugging. For normal use it adds maintenance with no real benefit.
Native packages and third-party builds
Some distributions carry native Bottles packages, but they lose the sandbox and the curated dependency set. The Arch Wiki repeats the same warning, noting that the developers strongly recommend Flatpak because it provides sandboxing. On Ubuntu, there is no good reason to go this route.
Creating Your First Bottle
Open Bottles and click the plus button to create a bottle. You will be asked for a name, an environment, and a runner.
Choosing an environment
For a business app such as an older accounting package or an Office-era utility, choose Software. For anything using DirectX 11 or 12 graphics, choose Gaming. Resist the urge to pick Gaming for everything. It enables overlays and translation layers you may not need, and they add overhead and occasional crashes in plain desktop programs.
Choosing a runner
Bottles offers its own Wine builds (Soda and Caffe are the typical defaults) and lets you download others such as Wine-GE or Proton variants. A reasonable rule of thumb from experience:
- Start with the default runner for the environment.
- If an application crashes at startup or renders black windows, try a different runner before touching anything else.
- Keep a note of which runner works for which program. A small text file in your documents folder saves repeated trial and error.
Running an installer
Inside the new bottle, click Run Executable, browse to the .exe or .msi, and let it run. After installation, Bottles can add the program to its own list so you can launch it with one click, and you can create a desktop entry from there.
If the executable sits in your Downloads folder and the file picker cannot see it, that is the Flatpak sandbox at work. The permissions section below explains the fix.
Dependencies, DXVK, and Components
Windows software often expects specific libraries. Bottles calls these “dependencies” and installs them from a built-in catalog.
Open your bottle, go to Dependencies, and search. Commonly needed items include:
- Core fonts, which fix garbled or missing text in older installers.
- Visual C++ runtimes of various years, required by a huge number of programs.
- .NET Framework versions, essential for many business applications.
- DirectX components for older games.
Install only what the program asks for. Piling on every runtime “just in case” bloats the bottle and sometimes introduces conflicts.
DXVK and VKD3D
DXVK translates DirectX 9, 10, and 11 calls to Vulkan. VKD3D-Proton does the same for DirectX 12. In a Gaming bottle both are typically enabled. They are the reason Windows games can run on Linux at near-native speed, but they also need working Vulkan, which is why the driver check earlier matters.
Shader caches
The first run of a game compiles shaders, which can cause stuttering. That is normal. It improves after the cache fills. Do not wipe cache folders casually if you have just fixed a stutter issue.
Flatpak Permissions: Giving Bottles Access to Your Files
A sandbox that cannot see your files is secure and annoying in equal measure. The fix is to grant access narrowly.
Using the command line
To allow access to a specific folder, for example a games drive mounted under /mnt/games:
flatpak override --user --filesystem=/mnt/games com.usebottles.bottlesFor a system-wide install, run it with sudo and without --user.
To see current overrides:
flatpak override --user --show com.usebottles.bottlesTo undo everything and return to defaults:
flatpak override --user --reset com.usebottles.bottlesUsing a GUI tool
Flatseal is a Flatpak app that exposes these permissions as toggles. It is far friendlier for people who rarely touch a terminal. Install it from Flathub and look for Bottles in the list.
What not to do
Do not grant --filesystem=host or --filesystem=home unless you truly need it. Windows programs, and especially anything of uncertain origin, then get read and write access to your personal files. The point of the sandbox is to limit blast radius. Give access to one folder, not the whole disk.
Backing Up and Managing Bottles
Bottles can export a bottle as a full or configuration-only backup from the bottle’s menu. A configuration backup is tiny and captures runner, settings, and dependency choices. A full backup includes the entire prefix and can be large.
You can also back up the data directory directly:
tar -czf bottles-backup-$(date +%F).tar.gz ~/.var/app/com.usebottles.bottles/Do this before major runner changes or distro upgrades. Rolling back from an archive beats rebuilding a prefix from memory.
Troubleshooting Common Problems
“flatpak: command not found”
Flatpak is not installed. Run sudo apt install -y flatpak, then log out and back in.
Bottles does not appear in the app menu after install
Export paths are not loaded yet. Restart the session. If it still does not show, run flatpak run com.usebottles.bottles to confirm it launches, then refresh the desktop database or reboot.
Installation fails with a remote or network error
Check that Flathub is configured.
flatpak remotesIf flathub is missing, re-add it. If the remote exists but downloads stall, try again later or repair the installation:
sudo flatpak repairBottles opens and immediately closes
Run it from a terminal to see the real message.
flatpak run com.usebottles.bottlesIf the error mentions a corrupt configuration, reset the app data after backing it up. A common last resort is moving ~/.var/app/com.usebottles.bottles aside and relaunching.
The file picker cannot see my files
This is the sandbox. Add a filesystem override for the folder, as shown earlier, or move the installer into a location Bottles can already reach.
Application crashes at launch or shows a black window
Try these in order.
- Switch to a different runner.
- Install the dependency the program expects (Visual C++, .NET, core fonts).
- Toggle DXVK or VKD3D off and on to test.
- Check the Windows version setting in the bottle’s compatibility options.
Very low FPS in games
Confirm Vulkan works with vulkaninfo --summary. If it lists only a software renderer such as llvmpipe, GPU drivers are missing or broken. Then confirm DXVK is enabled and that the correct GPU is selected on hybrid laptops.
On laptops with both integrated and discrete graphics, force the discrete one:
DRI_PRIME=1 flatpak run com.usebottles.bottlesNVIDIA setups may need a different offload approach, depending on driver version.
Missing 32-bit libraries or runtime errors
The Flatpak package bundles what it needs, which is one more reason to avoid native builds. Update and repair first.
flatpak update
flatpak repair --userStuttering or issues on Wayland
Ubuntu 26.04 uses GNOME 50 on Wayland. Wine apps generally run through XWayland and work fine, but some overlays, capture tools, and input behaviors differ. If a specific program misbehaves, test with a different runner before assuming the session type is at fault, and check the Bottles issue tracker for similar reports.
Audio crackling or no sound
Verify PipeWire is running.
systemctl --user status pipewire pipewire-pulseRestart it if needed with systemctl --user restart pipewire pipewire-pulse. Try changing the audio driver in the bottle’s settings if problems remain.
Regressions after an update
Updates can occasionally break specific combinations. A past Bottles release, for instance, had to patch Flatpak regressions affecting UMU Proton and MangoHud. If something that worked yesterday fails today, check the project’s issue tracker, then consider rolling back:
flatpak remote-info --log flathub com.usebottles.bottles
sudo flatpak update --commit=<commit-hash> com.usebottles.bottlesReplace the placeholder with a commit from the log output. Pin the app afterward only if you must, and unpin when a fix lands.
