Bottles: runners and application environments

Bottles turns the Wine Prefix concept into a tangible "Bottle", letting users manage Windows runtime environments with a click instead of at the command line. Runner names, defaults, and available components change between versions; check the actual component list.

The design philosophy behind Bottles#

The central abstraction in Bottles is a Bottle: an application environment that organizes a Wine Prefix, a runner selection, dependency records, and environment variables. Runners and components may live in shared directories, so a Bottle is not a fully self-contained archive.

Bottles does not perform code translation. All underlying operations ultimately call the Wine/Proton command-line interfaces. Its value lies in removing configuration friction.

The runner system#

A runner is the compatibility engine and associated patch set used to execute Windows programs. Bottles selects and invokes it; Bottles does not implement the complete Windows API itself. Check the component list in your version of Bottles for the actual downloadable names, builds, and defaults.

graph TD
    B[Bottles 管理器] --> C[Caffe 等 Wine runner]
    B --> S[Soda 等特定组件渠道]
    B --> V[Vaniglia 基线 runner]
    B --> E[其他已核对的运行器]
    E --> U[若使用 GE-Proton 则确认 umu 支持路径]

Soda

The source material describes Soda as a runner choice for gaming. Do not treat that historical name as today's recommended default, or assert its Wine base, TKG/GE patch set, or current version without manifest/release evidence. If your installation still offers Soda, record its exact version, architecture, download source, and test results with the target application.

Caffe

The official Bottles runner documentation describes Caffe as a runner with patches and improvements for games and applications. It should not simply be equated with a minimally patched, office-only Wine. Different versions under the same name can still differ in compatibility. Start with a version that runs the application reliably, then test new runners separately.

Vaniglia

The official documentation describes Vaniglia as a relatively clean runner, but it still applies wine-staging patches and a theme, so it is not an entirely unpatched upstream baseline. It can serve as one comparison point. To determine whether a bug comes from Bottles, keep the application, prefix state, dependencies, graphics components, and other conditions the same as well.

Selection strategy: start with the current Bottles environment recommendations and runners verified for your target application. Do not turn “Soda for games, Caffe for office work” into a fixed rule. For Steam games, prefer Proton within Steam. Official support for GE-Proton outside Steam is through umu; verify whether your manager provides that integration.

Dependency management and one-click installation#

Missing runtime components are the most common cause of failures in Windows applications. Bottles organizes dependencies into categorized, one-click installation options:

框架类:
  - dotnet48          # .NET Framework 4.8
  - dotnetcore3       # .NET Core 3.1
  - mono              # Mono 运行时

运行时类:
  - vcredist2019      # 示例名称；实际 VC 运行时版本按组件 manifest 核对
  - vcredist2015      # Visual C++ 2015 运行时
  - allfonts          # 常用 Windows 字体

游戏类:
  - d3dx9             # DirectX 9 扩展库
  - d3dcompiler_43    # D3D 着色器编译器
  - xact              # Xbox Audio Creation Tool

媒体类:
  - mf-install        # 历史外部方案名称，不能当作当前 Bottles 内置依赖
  - lavfilters        # LAV Filters 解码包

Bottles uses component/dependency definitions to download and install software; its dependency system as a whole is not equivalent to winetricks. The table above illustrates categories by purpose and does not guarantee that all those names are available in the current component catalog. For example, an external Media Foundation script is not automatically a built-in dependency. Check the installers, licenses, versions, and prefix architecture. A failed installation does not mean a full rollback has happened automatically. Create verifiable restore points and backups before important changes.

Environment isolation and snapshots#

Bottle-level isolation

Each Bottle has its own:

• Prefix directory (virtual C drive and registry)
• Runner version
• Dependency list
• Environment variables
• Sandbox policy

These settings are generally separate, but a Bottle is not an independent security boundary. Bottles may still share host files, network access, permissions, and components. Programs (such as Office 2016 and Photoshop) can be placed in different Bottles, each with its own reported Windows version and DLL overrides, without conflicting.

State snapshots and restore points

Bottles Versioning centers on file states and restore points. The official description explains differential indexing of added, deleted, and modified files. That does not establish that it uses filesystem-level CoW, or that it saves complete system snapshots, the memory of running processes, or external files.

• Before changing dependencies or the registry, close the application and create a state with a description.
• Check which directories and settings your version indexes. Back up external saves, shared runners, Steam Cloud state, and host files separately.
• After restoring, check the application, dependencies, and data again. A success notification is not a substitute for full verification.
• Measure actual disk usage. Differential indexing does not automatically mean block-level CoW on every filesystem.

Restore points reduce the cost of configuration experiments, but they do not replace independent backups or guarantee automatic rollback after a failed installation.

Flatpak installation and considerations#

Bottles officially recommends installation through Flatpak:

flatpak install flathub com.usebottles.bottles
flatpak run com.usebottles.bottles

Flatpak permissions, GPUs, and file access

Flatpak runtimes and graphics extensions provide matching user-space graphics libraries. You do not need to expose the host's /run/opengl-driver, /sys, or entire root directory to the application by default. NVIDIA extensions must match the host driver; AMD/Intel generally use the runtime's Mesa/GL extensions. Forcing a host ICD JSON path may point to libraries that do not exist inside the sandbox or are incompatible with it.

First inspect the actual runtime, permissions, and overrides:

flatpak info com.usebottles.bottles
flatpak info --show-permissions com.usebottles.bottles
flatpak override --user --show com.usebottles.bottles
flatpak list --runtime

A successful host-side vulkaninfo run only verifies that tool's graphics stack on the host. Inside a Bottle, you still need to check the runner, DXVK/VKD3D logs, and the device the game actually uses. If extensions are missing or versions do not match, fix the runtime/driver relationship rather than hiding the problem with broad permissions.

Default file permissions depend on the app manifest and the actual installation; do not assume access to the entire home directory. The file-chooser portal can grant access to individual files. If an external games directory is genuinely needed, grant the minimum permission for that specific path:

# 内容示例：仅授权这个已确认的游戏目录，不授权整个宿主。
flatpak override --user --filesystem=/mnt/games com.usebottles.bottles

Flatseal can help inspect permissions, but changes affect the isolation boundary. For font problems, first check the fonts in the Bottle and their Chinese character coverage, then use dependency management or lawfully installed font files. Do not blindly expose /usr/share/fonts: Flatpak's reserved directories and actual font integration mechanism may make that override ineffective. Prefixes and DLL overrides do not block network access either.

The official Versioning/runner documentation describes mechanisms and some historical interfaces; it does not guarantee that the current UI is identical. Bottles was not run and installation success was not verified for this article.

Sources and verification limits#

The references below define the relevant mechanisms and support boundaries. Installation, building, activation, prefix state, and actual application behavior must each be verified in the target environment. The example commands do not imply a successful run on any host.

• Bottles runner documentation
• Bottles Versioning
• Flatpak graphics extensions
• Flatpak sandbox permissions