What is Bottles?

Bottles is an application that allows you to easily manage Windows prefixes on your favorite Linux distribution.

Windows prefixes?

Windows prefixes are environments where it is possible to run Windows software using runners. Runners are compatibility layers capable of running Windows applications on a Linux system.

In Bottles we call these environments bottles.

Where to start?

First run

Types of runners

There are two types of runners in Bottles:

• Wine

• Proton

The Wine runner is used for all Environments and is therefore in all bottles created, but also for external prefixes imported into Bottles. We support 4 different runners:

• Lutris (from Lutris Developers)

• Vaniglia (our vanilla runner, available by default since Bottles v3)

Caffe is a powerful runner that came with a large set of patches and improvements for Gaming and Software.

Vaniglia (Vanilla) is a clean runner as its name suggests. Apply only wine-staging patches and a modern theme created by Joshua Ashton.

The Proton runner can be installed from the Bottles Preferences page and chosen on a bottle creation by selecting the Custom Environment. You can also switch from Wine to Proton at any time by changing your bottle preferences.

Runner updates

You can install new runners by clicking the download button next the runner of your interest.

If you're feeling fearless, you can enable Release Candidates ("Pre-release" option) to download and then test premature versions of runners, which may include greater software compatibility at the cost of bugs and possible regressions.

How to add unlisted runners?

At the first start you will be shown the Onboard, which is a wizard that will explain some concepts and help you configure Bottles.

Once the key concepts of Bottles have been introduced, some important stuff (~ 70MB) will be downloaded, which is necessary for creating your bottles.

• Caffe runner

• DXVK

• VKD3D

• NVAPI

• LatencyFleX

• Runtime

Each file is checked with the repository checksum, if this check fails, the file is deleted and the installation fails.

This is a one time operation, you can use the same runner for all your bottles or install others from the Bottles preferences.

Finally everything is ready and you can start using Bottles!

Below is a video showing the process of first boot, first bottle creation and running a Windows program.

Offline? You do not have time?

Are you offline or don't want to download it now? No problem.

If you are Offline, Bottles will notice and ask you to go online to proceed. All features that require a connection are blocked and will be active again as soon as you come back online!

You can go to the Bottles Preferences at any time and install a runner. Alternatively, when you create a bottle, you will be automatically taken to the installation page.

Your first Bottle

When everything is ready, you will be faced with a screen like the following, telling you that there is no bottles yet.

To create your first bottle, you will need to press the plus button on the top left and proceed following the on-screen instructions.

You can read more about the different types of bottles in the next section.

Mainly dxvk is a .dll override bundle which, integrated in a wine prefix, allows you to detect and translate calls from DirectX to Vulkan. This is done automatically, without any user intervention.

How to enable

Basic DXVK is installed and enabled by Bottles when creating a bottle in the following environments:

• Gaming environment

• Software environment

You can check its activation from the bottle preferences, checking the "DXVK for Direct3D" voice.

When this component is enabled, a backup of the old dlls is created in the wineprefix and automatically recovered when disabled.

To manually activate it in any bottle, simply enable the switcher from the bottle preferences.

DXVK updates

You can keep this component updated from main Bottles preferences ("DLL Components" tab).

To change the DXVK version used by a particular bottle, open the "Preferences" tab of your bottle and expand the "Components version" drop-down list in the "System" section.

Environment variables

DXVK came with a large number of environment variables to better configure it.

• DXVK_STATE_CACHE_PATH is preconfigured and points to the root path of the bottle

• DXVK is preconfigured to compiler otherwise is set to devinfo, memory, drawcalls, fps, version, api, compiler if enabled from the settings for Developers and Debug in the bottle

Bottles Environments offers a package of configurations and dependencies to enhance support for Windows software in some contexts.

We offer the following default Environments:

• Gaming for games

• Application for... applications

• Custom is just a clear workspace where you can start making experiments

Gaming environment

This environment comes with the following configuration:

• DXVK enabled

• VKD3D disabled

• Esync enabled

• Discrete Graphics Card enabled (useful for laptops with hybrid graphics setup)

• PulseAudio latency forced to 60ms for better audio quality in-game

• d3dx9, d3dcompiler_43, d3dcompiler_47 dlls

• Microsoft Line Services

• Arial, Times and Courier fonts

Application environment

This environment enables DXVK and VKD3D by default, ensuring support for multimedia applications (such as 3D modeling, Video Editing and drawing programs) but also office and productivity software. It will also install Arial, Times and Courier fonts, and the Wine mono, replacing the .NET Framework.

Custom environment

If you are a nerd (even more nerd) then this is the environment for you!

This is a clear environment where you can experiment, test and configure your bottle! You can also choose which runner to use for your experiments, just install more from the Bottles Preferences page.

Environment preferences

Regardless of the environment you choose, you can change your preferences at any time, e.g. change the type of synchronisation or add and remove dependencies.

This is one of the most important sections, here you can configure and tweak your bottle.

This page is divided into four sections:

• Graphics

• System

• Audio

• Developers & Debug

From the System section you can:

• change the components (runner, dxvk...) versions

• choose the synchronization type

• change the Windows version

• change the working directory (the path where the executable will be executed)

• register new DLL Overrides and environment variables

• manage drives for accessing files inside bottle

• and more...

In the Audio section you can toggle the "Reduce PulseAudio latency" feature which improves the audio quality for some games.

The Developer & Debug section offers some utilities for developers. Here you can show the wine fixme logs and enable the DXVK HUD or MangoHud to display the FPS counter, draw calls, dxvk versions and other information.

Runtime

Runtime is a lib bundle which maintains the compatibility for installers, it is available by default on Flatpak packages instead for other package types (e.g AUR, Fedora, …) you will need to install it from the program preferences.

An executable can be used to start or install a program in a bottle. In Bottles you can run these files in two ways:

• from the GUI using the Run executable feature

• using the CLI (this can be useful if you don't want to show Bottles GUI)

Launch from GUI

Under the bottle name we find the Run executable button:

Pressing it will open a window from which to select the executable of our interest, once selected it will be executed in the bottle.

Launch with arguments

Some applications require you to start with arguments. As you can see from the previous image, next to Run executable there is an arrow, by pressing it you can select the item Run with arguments. Once pressed, a screen will appear where you can enter our arguments:

Once finished, we press on Run and select the executable to start it in the bottle.

Launch from CLI (supports .lnk)

To start an executable from the CLI, we can proceed in two ways.

Simply passing the path of the executable to the command to start Bottles, the GUI will appear asking which bottle to start it. It is also possible to tell Bottles from the preferences to close automatically after starting the executable.

Otherwise you can avoid the GUI by specifying the parameters:

In this way the Bottles GUI will not be displayed, useful if we want to create a custom Desktop Entry to start our favorite applications.

These are the shortcuts available in Bottles:

Every bottle has its own configuration file, located at the bottle root directory. It contains required dependencies and the installed program.

To access Bottles preferences, just press the menu button and select Preferences.

Preferences shows four sections:

• General

• Runners

• DLL Components

• Experiments

General

In the General section you can configure the Bottles appearance and general settings.

Appearance settings:

• Toggle dark mode (turn off the lights)

• Show update date (this will toggle the last edit date in the bottles list)

General settings:

• Notifications (choose if Bottles should display notifications in your desktop)

• Temp files (toggle to prune the temp directory on Bottles start, this will reduce the disk used by Bottles but also forcing re-download dependencies when installing in new bottles)

• Close Bottles after starting a program (this works only when Bottles was started from the file manager or using the CLI)

Advanced settings:

• Custom bottles path (specifies the directory that Bottles should use to search for existing bottles and create new ones)

Runners

DLL Components

Experiments

The Experiments sections allows you to enable functions that are currently under active development and may work unstable. Use them at your own risk.

Bottles searches the bottle for the installed software and places them in the programs section of the bottle.

The search is done through the common Start Menu directories, Bottles looks for all the .lnk files in these directories and extracts some information such as: name of the application and path of the executable.

Launch installed programs

After installing a software application in the bottle, just go to the Programs section to start it.

Add сustom programs

Hide programs

You can hide those programs that you don't want to see in the installed list. To do this, open the context menu of the program (the icon with the 3 dots) and select the "Remove from Programs" option.

Custom arguments

Some programs may require arguments to be passed to the executable. To set them you can open the context menu and choose "Change launch options".

A field will appear where you can enter the arguments of the executable, once done press Save at the top right and start the program. Bottles will remember the arguments for that executable, so you don't have to add them again.

In the "Advanced options" section, you can specify the script that will be run immediately after your application is launched.

Prefix and suffix in launch options

The %command% placeholder can be used in the Launch Options to customize prefixes and suffixes:

my_command %command% -flag1 -flag2

Add programs to your Desktop

To add a program in your Desktop Applications menu, choose "Add Desktop Entry" in the program's menu.

Flatpak

The Flatpak version need a special permission to generate desktop entries. To achieve this, close Bottles and open your terminal, then type:

flatpak override com.usebottles.bottles --user --filesystem=xdg-data/applications

then start Bottles again.

We also made a video tutorial using Flatseal:

Add programs in Steam

Since Bottles 2022.5.28, it is possible to add programs in your Steam client, useful for Steam Deck users who want to launch their games without having to launch the Bottles GUI.

To achieve this just choose "Add to Steam" in the program's menu and restart Steam.

Flatpak

Bottles Flatpak need special permissions to add shortcuts to Steam. Close Bottles and open your terminal, then type:

flatpak override com.usebottles.bottles --filesystem=~/.local/share/Steam
flatpak override com.usebottles.bottles --filesystem=~/.var/app/com.valvesoftware.Steam/data/Steam

then start Bottles again.

The program does not appear

Here you can extend your bottle compatibility adding new dependencies. These are Windows software and libraries installed by Bottles trough automation.

Some dependencies examples are:

• vcredist (2013, 2015, 2019)

• dotnet (3.5, 3.5 sp1, 4.0, 4.7.2, 4.8)

• dotnetcore3

• msxml (3, 6)

• d3dx9,

• d3compiler (43, 46, 47)

• ffdshow

• dirac

A new state will be generated after the dependency installation.

Dependencies can also automatically be installed by the official Bottles installers. So if you choose to install e.g. the epicgamestore installer, you will see the new dependencies installed after the process. If you want to install them again, you can do it using the context menu (three dots at the right side of a dependency).

Multiple selection

In this mode, you can select several dependencies at once and, by clicking on the "Install selected" button, install them all at once. However, the use of this mode currently is not recommended due to possible installation problems.

Packing dependences

The third version of Bottles (Treviso) introduced a new feature called Versioning.

This is a versioning system for your bottles, based on user-defined restore points, allowing you to restore the bottle to a previous state when something goes wrong. Useful if you are testing multiple configurations.

How versioning works

Versioning works through recovery points called states. The first recovery point is used as an index of the bottle files. Whenever a new state is created, Versioning checks the differences between the current files and those in the index of the previous state (by checking the checksums of the new, missing and updated files). When it detects changes, they are recorded in the index of the new state.

Below is an example of a state index created after installing the Comic font in the bottle:

{
    "Update_Date": "2021-07-02 21:52:18.906569",
    "Additions": [
        {
            "file": "windows/Fonts/Comic.TTF",
            "checksum": "a50f9c96a76356e3d01013e0b042989f"
        },
        {
            "file": "windows/Fonts/ComicBD.TTF",
            "checksum": "81d64ec3675c4adc14e9ad2c5c8103a7"
        }
    ],
    "Removed": [],
    "Changes": []
}

As we can see, Versioning detected the presence of new files and added them to the index. If we restore the previous state to the one just created, the Comic font will be removed.

Each state requires a comment during creation (it will be used to recognize it when necessary), and the creation date is also saved to provide more details to the user.

The currently active state is highlighted in purple.

To restore a state it is necessary to press the icon with the clock to the right of the desired state.

How to use versioning

You can use versioning with a new bottle or an existing one.

On bottle creation

The versioning is available during the creation of the bottle, only if you select the "Custom" environment, then checking "Use versioning" from the Advanced options.

In this way, a restore point will be created as soon as the bottle is created and versioning will take effect.

In existing bottles

Versioning can be enabled for any existing bottle by simply selecting the Versioning section in the bottle details and creating a new state that will be used as the bottle's initial index.

We can understand if versioning on a bottle is active, through the purple icon in the bottle list and in the detail of the same, this also shows the number of the current state.

Installers are a set of rules used by Bottles to install a program in a bottle, in a completely silent and automated way.

These installers take care of configuring the bottle, installing the necessary dependencies, installing the software and making it available to the user with settings that ensure that everything works in the best way.

The novelty introduced by our own installers is the use of the integrated dependency system. This in fact does not use external scripts to install and configure dependencies but uses the same dependency manager accessible from Bottles, so each one of these is automatically managed by Bottles, in the same way you would do it manually from the dependencies page.

Each installer configures the executable in your system (at the moment it does not happen if you are using Flatpak), allowing you to access it at any time from the applications menu of your Desktop Environment. These are done through the Bottles CLI, making sure they use your bottle’s configuration and environment.

Use installers

Below is a video showing how to use the Installers in Bottles.

To use the installers you obviously need a bottle, so select the one you are interested in or create a new one. In the sidebar access the Installers section.

Choose the installer you want and press the download icon. It will automatically configure your bottle and install the program. When the installation finish, you will see a new entry in your bottle's programs list.

Compatibility grades

Each installer is marked with a compatibility grade based on the results of the testing. If the software is at least usable it is marked as Bronze and better it works higher is going to be considered with a maximum value of Platinum.

The grades are (from worse to best): Bronze, Silver, Gold, Platinum

Note for architecture

Important note installers can declare their architecture so if the bottle created is Win64 it won't see Win32 installers and vice versa.

Refresh installation

Installers can be installed multiple times, also in the same bottle. If you break anything or just want to use the latest installer (as these can receive updates from maintainers), just install it again. Currently Bottles doesn't notify installers updates but will be able to do so in the near future.

Import from other managers

Currently we support migration from these applications:

• Bottles V1

• Lutris

• PlayOnLinux

How to import

You can access the import tools from the Bottles main menu by selecting the "Import/export" option.

The "Importer" window will open.

How to backup

Backup types

In Bottles you can export your bottles with ease and in multiple ways:

• Config backup

• Full backup

• Duplicate

The config backup ("Configuration" option) make a copy of your bottle configuration (the bottle.yml file in the bottle root), this can be provided to other users to replicate your bottle configuration or attached to a report when you are facing problems.

The full backup ("Full archive" option) make an archive with a full copy of your bottle directory (comprehensive of configuration and files) and let you store it wherever you want.

You can also duplicate a bottle ("Duplicate bottle" option) with a different name. This can also be used to create bottles with a template, so make a new bottle with tweaked configuration and some dependencies, then duplicate to use the same environment in a new bottle.

Import backups

Starting from version 2022.6.28, Bottles allows you to manage Steam Proton prefixes by enabling the setting of the same name.

If you have installed Bottles via Flatpak, it is essential to give it permissions to access the Steam path, otherwise the integration will not be activated.

Proceed according to your Steam installation.

Steam non-Flatpak

flatpak override --user com.usebottles.bottles --filesystem=xdg-data/Steam

Steam Flatpak

flatpak override --user com.usebottles.bottles --filesystem=~/.var/app/com.valvesoftware.Steam/data/Steam

then restart Bottles.

In 2022.3.28 we have introduced a new CLI interface, which provide more features then the prior.

Launch CLI

The new interface has a dedicated command: bottles-cli .

If using Bottles as Flatpak (the suggested way), launch it with:

flatpak run --command=bottles-cli com.usebottles.bottles --help
Bottles is a tool to manage your bottles

positional arguments:
  {info,list,programs,tools,reg,edit,new,run}
                        sub-command help
    info                Show information about Bottles
    list                List entities
    programs            List programs
    tools               Launch WINE tools
    reg                 Manage registry
    edit                Edit a bottle configuration
    new                 Create a new bottle
    run                 Run a program

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -j, --json            Outputs in JSON format

for all other packages:

bottles-cli --help

Interfaces/Arguments

Since Bottles has a lot of features, to keep things organized we have divided it in multiple interfaces: info, list, programs, tools, reg, edit, new, run.

Info

The info interface can be used to access Bottles information:

usage: bottles-cli info [-h] {bottles-path,health-check}

positional arguments:
  {bottles-path,health-check}
                        Type of information

optional arguments:
  -h, --help            show this help message and exit

List

The list command is meant to be used for listing Bottles stuff:

usage: bottles-cli list [-h] [-f FILTER] {bottles,components}

positional arguments:
  {bottles,components}  Type of entity

optional arguments:
  -h, --help            show this help message and exit
  -f FILTER, --filter FILTER
                        Filter bottles and components (e.g. '-f 'environment:gaming')

the -f argument for bottles supports the environment prefix:

bottles-cli list bottles -f environment:gaming

while for components the category one can be used:

bottles-cli list components -f category:dxvk

Programs

The programs interface can be used to list all programs in a bottle (only added by users or installers).

usage: bottles-cli programs [-h] -b BOTTLE

optional arguments:
  -h, --help            show this help message and exit
  -b BOTTLE, --bottle BOTTLE
                        Bottle name

Tools

The tools interface can be used to launch any WINE utility.

usage: bottles-cli tools [-h] -b BOTTLE {cmd,winecfg,uninstaller,regedit,taskmgr,control,explorer}

positional arguments:
  {cmd,winecfg,uninstaller,regedit,taskmgr,control,explorer}
                        Tool to launch

optional arguments:
  -h, --help            show this help message and exit
  -b BOTTLE, --bottle BOTTLE
                        Bottle name

Reg

The reg interface can be used to access and edit the bottle's Windows registry.

usage: bottles-cli reg [-h] -b BOTTLE -k KEY -v VALUE [-d DATA] [-t {REG_DWORD,REG_SZ,REG_BINARY,REG_MULTI_SZ}] {add,edit,del}

positional arguments:
  {add,edit,del}        Action to perform

optional arguments:
  -h, --help            show this help message and exit
  -b BOTTLE, --bottle BOTTLE
                        Bottle name
  -k KEY, --key KEY     Registry key
  -v VALUE, --value VALUE
                        Registry value
  -d DATA, --data DATA  Data to be set
  -t {REG_DWORD,REG_SZ,REG_BINARY,REG_MULTI_SZ}, --key-type {REG_DWORD,REG_SZ,REG_BINARY,REG_MULTI_SZ}
                        Data type

Edit

The edit interface can be used to edit a bottle (e.g. any parameter, environment variables, Windows version, runner, dxvk, vkd3d..).

usage: bottles-cli edit [-h] -b BOTTLE [--params PARAMS] [--env-var ENV_VAR] [--win WIN] [--runner RUNNER] [--dxvk DXVK] [--vkd3d VKD3D] [--nvapi NVAPI] [--latencyflex LATENCYFLEX]

optional arguments:
  -h, --help            show this help message and exit
  -b BOTTLE, --bottle BOTTLE
                        Bottle name
  --params PARAMS       Set parameters (e.g. '-p dxvk:true')
  --env-var ENV_VAR     Add new environment variable (e.g. '-env-var WINEDEBUG=-all')
  --win WIN             Change Windows version (e.g. '--win win7')
  --runner RUNNER       Change Runner (e.g. '--runner caffe-7.2')
  --dxvk DXVK           Change DXVK (e.g. '--dxvk dxvk-1.9.0')
  --vkd3d VKD3D         Change VKD3D (e.g. '--vkd3d vkd3d-proton-2.6')
  --nvapi NVAPI         Change DXVK-Nvapi (e.g. '--nvapi dxvk-nvapi-1.9.0')
  --latencyflex LATENCYFLEX
                        Change LatencyFleX (e.g. '--latencyflex latencyflex-v0.1.0')

Add

The add interface can be used to add new programs to a bottle:

usage: bottles-cli add [-h] -b BOTTLE -n NAME -p PATH [-l LAUNCH_OPTIONS] [--no-dxvk] [--no-vkd3d]
                       [--no-dxvk-nvapi]

optional arguments:
  -h, --help            show this help message and exit
  -b BOTTLE, --bottle BOTTLE
                        Bottle name
  -n NAME, --name NAME  Program name
  -p PATH, --path PATH  Program path
  -l LAUNCH_OPTIONS, --launch-options LAUNCH_OPTIONS
                        Program launch options
  --no-dxvk             Disable DXVK for the program
  --no-vkd3d            Disable VKD3D for the program
  --no-dxvk-nvapi       Disable DXVK Nvapi for the program

New

The new interface can be used to create a new bottle.

usage: bottles-cli new [-h] --bottle-name BOTTLE_NAME --environment ENVIRONMENT [--custom-environment CUSTOM_ENVIRONMENT] [--arch ARCH] [--runner RUNNER] [--dxvk DXVK] [--vkd3d VKD3D] [--nvapi NVAPI] [--latencyflex LATENCYFLEX]

optional arguments:
  -h, --help            show this help message and exit
  --bottle-name BOTTLE_NAME
                        Bottle name
  --environment ENVIRONMENT
                        Envorinment to apply (gaming|application|custom)
  --custom-environment CUSTOM_ENVIRONMENT
                        Path to a custom environment.yml file
  --arch ARCH           Architecture (win32|win64)
  --runner RUNNER       Name of the runner to be used
  --dxvk DXVK           Name of the dxvk to be used
  --vkd3d VKD3D         Name of the vkd3d to be used
  --nvapi NVAPI         Name of the dxvk-nvapi to be used
  --latencyflex LATENCYFLEX
                        Name of the latencyflex to be used

Run

The run interface can be used to launch an executable from a given path or any program in a bottle using its name:

usage: bottles-cli run [-h] -b BOTTLE [-e EXECUTABLE] [-a ARGS] [-p PROGRAM]

optional arguments:
  -h, --help            show this help message and exit
  -b BOTTLE, --bottle BOTTLE
                        Bottle name
  -e EXECUTABLE, --executable EXECUTABLE
                        Path to the executable
  -a ARGS, --args ARGS  Arguments to pass to the executable
  -p PROGRAM, --program PROGRAM
                        Program to run

Shell

The shell interface can be used to run commands inside a wine shell for the given bottle:

usage: bottles-cli shell [-h] -b BOTTLE -i INPUT

optional arguments:
  -h, --help            show this help message and exit
  -b BOTTLE, --bottle BOTTLE
                        Bottle name
  -i INPUT, --input INPUT
                        Command to execute

Standalone

The standalone interface can be used to generate a script which can be used to launch commands in a wine shell for the given bottle, without passing trough Bottles:

usage: bottles-cli standalone [-h] -b BOTTLE

optional arguments:
  -h, --help            show this help message and exit
  -b BOTTLE, --bottle BOTTLE
                        Bottle name

Developers mode

We've added a --json global argument to help developers accessing stuff from the Bottles' CLI. It can be used with any interface and will return the output in JSON format. Some examples:

bottles-cli --json info health-check
{"Display": {"X.org": true, "X.org (port)": ":99.0", "Wayland": false}, "Graphics": {"vendors": {"nvidia": {"vendor": "nvidia", "envs": {"__NV_PRIME_RENDER_OFFLOAD": "1", "__GLX_VENDOR_LIBRARY_NAME": "nvidia", "__VK_LAYER_NV_optimus": "NVIDIA_only"}, "icd": "/usr/lib/x86_64-linux-gnu/GL/vulkan/icd.d/nvidia_icd.json:/usr/lib/i386-linux-gnu/GL/vulkan/icd.d/nvidia_icd.json"}, "amd": {"vendor": "amd", "envs": {"DRI_PRIME": "1"}, "icd": "/usr/lib/x86_64-linux-gnu/GL/vulkan/icd.d/radeon_icd.x86_64.json:/usr/lib/i386-linux-gnu/GL/vulkan/icd.d/radeon_icd.i686.json"}}, "prime": {"integrated": {"vendor": "amd", "envs": {"DRI_PRIME": "1"}, "icd": "/usr/lib/x86_64-linux-gnu/GL/vulkan/icd.d/radeon_icd.x86_64.json:/usr/lib/i386-linux-gnu/GL/vulkan/icd.d/radeon_icd.i686.json"}, "discrete": {"vendor": "nvidia", "envs": {"__NV_PRIME_RENDER_OFFLOAD": "1", "__GLX_VENDOR_LIBRARY_NAME": "nvidia", "__VK_LAYER_NV_optimus": "NVIDIA_only"}, "icd": "/usr/lib/x86_64-linux-gnu/GL/vulkan/icd.d/nvidia_icd.json:/usr/lib/i386-linux-gnu/GL/vulkan/icd.d/nvidia_icd.json"}}}, "Kernel": {"Type": "Linux", "Version": "5.16.15-201.fc35.x86_64"}, "Distro": {"Name": "GNOME", "Version": "\"42 (Flatpak runtime)\""}, "Tools": {"cabextract": true, "p7zip": true, "patool": true, "glibc_min": "2.33"}, "Bottles_envs": null}

bottles-cli --json list components -f category:runners
{"runners": ["vaniglia-7.5", "sys-wine-7.0", "caffe-7.5", "caffe-7.1"]}

in some cases it will return more info then the classic launch, e.g. for the programs interface:

bottles-cli --json programs -b MyBottle
[{"executable": "Battle.net.exe", "arguments": "", "name": "Battle.net", "path": "C:\\Program Files (x86)\\Battle.net\\Battle.net.exe", "folder": "", "icon": "", "script": null, "removed": null}, {"executable": "EpicGamesLauncher.exe", "arguments": "-opengl -SkipBuildPatchPrereq", "name": "Epic Games Store", "path": "C:\\Program Files (x86)\\Epic Games\\Launcher\\Portal\\Binaries\\Win32\\EpicGamesLauncher.exe", "folder": "", "icon": "", "script": null, "removed": null}, {"executable": "GalaxyClient.exe", "arguments": "--in-process-gpu /runWithoutUpdating /deelevated", "name": "GOG Galaxy", "path": "C:\\Program Files (x86)\\GOG Galaxy\\GalaxyClient.exe", "folder": "", "icon": "", "script": null, "removed": null}]

Migrate to Flatpak

In recent versions of the Flatpak and, the bottles are saved in a different location than the other packages, respecting the structure of the Flatpak package.

Paths differences

The other packages save the essential Bottles files, such as components, temps, and bottles, in the directory: ~/.local/share/bottles . Flatpak saves these files in the Flatpak data directory: ~/.var/app/com.usebottles.bottles/data/bottles.

Migrate old bottles to Flatpak

The migration is simple as it sounds - just move (or copy) the content of the path ~/.local/share/bottles to the new one ~/.var/app/com.usebottles.bottles/data/bottles

Restart Bottles and that's it.

xdg-open syntax

xdg-open command opens a file or URL in the user's preferred application. General syntax:

xdg-open {file | URL}

Bottles URL syntax

The link to run the program in a bottle has the following syntax:

bottles:run/<bottle>/<program>

Where

<bottle> is the name of the bottle (displayed in the interface, or the "Name" parameter in bottle.yml);

<program> is the name of the program for launch (displayed in the interface, or the "name" parameter of the corresponding program in bottle.yml).

Usage

For example, to run the program "Notepad" in the bottle "MyLittleBottle", the full xdg-open command will look like this:

xdg-open bottles:run/MyLittleBottle/Notepad

Or you can just use the bottles:run/MyLittleBottle/Notepad URL in your browser.

First the basics

The repository consists of 3 main points:

• the index.yml file that is the index of all dependencies available in the repository

• the Essentials and Fonts categories (in the future there will be more) where all the dependencies manifests are collected

• the dependency manifest

The index.yml file looks like:

How you can see, every dependency is index with it's name, the description and the category where it is located.

Each manifest has a bunch of mandatory data:

• Name

• Description

• Provider

• License and License_url

• Dependencies (not implemented so leave it blank)

• Steps

The Name should reflect the manifest file name (e.g. allfonts for allfonts.yml).

The Description is the full name of the dependency (e.g. All Microsoft and Adobe essential fonts)

The Provider is the owner of the source where the dependency files are located. This can also be the name of the creator of the software (e.g. Microsoft).

License and License_url should be filled with the license name and url of the dependency we are going to install, normally these are offered with the software itself (e.g. Microsoft EULA, in case of multiple licenses, only the main license can be specified: Mostly Microsoft EULA).

The Steps are the instructions to follow to install the dependency. Bottles takes into account the order in which these are written and executes them in the same order.

Propose new dependencies

There are two ways of proposing new dependencies:

Some programs may fail to start or show a black screen when unable to access files. This is due to the Flatpak sandbox, as the executable was started from outside the sandbox and the runner is unable to access some necessary files. Nonetheless, it's easy to fix without having to disable the sandbox.

How to fix

To fix the problem, just place the files inside the sandbox, an easy process that takes a few seconds. Access the bottle screen where we want to launch the executable and press on Browse C:

This will popup the system file manager to the bottle C: drive path, then paste your files here (normally these problems doesn't came with standalone executable, therefore you should have a folder with multiple files, for example as a result of an extraction, then copy the entire folder, not the single executable).

After placing the files, go back to Bottles and access the Programs section from the sidebar and Add a new program: by clicking the + in the headerbar, here browse to the folder and pick the executable. Next time start it from the Programs section and it should start finding all the needed files.

There are two ways to catch out the logs from Bottles:

• using your System Terminal

• using the Wine Debugger Console

Let's face them both together.

System Terminal

To capture all Bottles and wineprefixes logs, just start Bottles itself through the Terminal installed on the system, for example through:

• GNOME Terminal

• Konsole

• XFCE4 Terminal

• MATE Terminal

• xterm

• etc.

For example, if you installed Bottles via AppImage:

cd /path_to_appimage
./Bottles*.AppImage

This way you will receive all the logs in the Terminal (which must remain open).

Logging levels

Using this method you will also see logs from Bottles and not only from runners. The following are the logging levels to better read and understand logs:

• [INFO] This log informs the correct functioning of one or more operations performed by Bottles.

• [WARNING] It is shown when an operation has been performed but there are one or more non-blocking warnings.

• [ERROR] An error occurred and the operation was not completed.

• [CRITICAL] The sudden error may have jeopardized Bottles from functioning correctly or an exception was not handled.

Wine Debugger

Wine comes with a built-in debugger (winedbg) for analyzing processes running in a wineprefix.

Wine debugger has several useful abilities, including the one to generate backtraces, set breakpoints, and even disassemble code. It supports a subset of the gdb commands, especially the most common ones. For instance you can use info proc and info thread and then attach to a given process, which can be very useful for running backtraces on deadlocks.

Attach to a process

First run a Windows executable file in your bottle, then launch winedbg using the Debug voice in the Utility section from your bottle details.

The system Terminal will run with winedbg running inside your bottle.

Backtrace for all running processes

To get the backtrace of all running processes in the wineprefix, type:

bt all

Backtrace from specific process

To receive the backtrace of a specific process, type:

info process

to list all active processes in the wineprefix.

Wine-dbg>info process
 pid      threads  executable (all id:s are in hex)
 0000010c 2        'conhost.exe'
 000000fc 1        'npp.7.9.2.Installer.exe'
 00000060 3        'explorer.exe'
 00000038 7        'services.exe'
 000000cc 6        \_ 'rpcss.exe'
 000000a4 3        \_ 'svchost.exe'
 00000080 5        \_ 'winedevice.exe'
 00000068 5        \_ 'plugplay.exe'
 00000044 4        \_ 'winedevice.exe'

Focus on the first column of the output where the process ID appears, let's attach the debugger to the process ID of interest:

Wine-dbg>attach 0x<pid> # where <pid> is the ID of our interest

This will give us the backtrace of the program if already crashed. Otherwise we can get it immediately by typing:

set $BreakOnFirstChance=0
cont

so keep using the program and on crash go back to Terminal to check the backtrace.

Despite this, there are some cases where you may want to explicitly expose directories to the Flatpak, e.g.:

• use the file chooser provided by the runner to open/save files in your system, outside the sandbox.

To achieve this, we can run the command

flatpak override --user --filesystem="path" com.usebottles.bottles

flatpak install flathub com.github.tchx84.Flatseal

At the first launch of Flatseal you need to select Bottles from the left menu, then scroll to the Filesystem section and make your choices.

We suggest to not expose all your system or home but manually add each directory in Other files. In the following example we are exposing the ~/Games folder from our home (the default location for Lutris windows prefixes).

Then the Bottles Importer will see the new directory.

In some specific cases it may be useful to have Bottles as a system WINE command, for example when a program needs to access the command and we want it to use a specific bottle.

Custom wine command

Make a new file named wine in ~/.local/bin or any directory in your PATH with the following content:

or the following if you are not using the Flatpak:

and change MyBottle to the name of your chosen bottle. Then make it executable:

Usage

Now just run:

to launch it with Bottles. It will automatically use your chosen bottle.

What's the homedir?

Each user has a personal homedir (/home/your_username), this is the place where you can store your personal files, like videos, photos or documents. This path is also used for cache files .cache and software configurations .config.

How do runners use my homedir?

It generates a folder in the users/ path, for the current logged in user (e.g. I'm currently logged as mirko, so the runner will create a mirko/ folder inside users/. It also creates a Public folder, but that is not our interest right now.

Each user folder contains some symlink to the original homedir:

So each program installed in the bottle can see your files from the linked folders.

Sandboxed userdir (homedir)

Starting from Bottles 2021.10.14, the userdir path is sandboxed, so the above symlinks don't exist.

Creating a new bottle, Bottles detect if it is running under Flatpak, then remove these symlinks and make them as normal folders inside the bottle. As a result, each program can only work with files inside the sand-boxed userdir (shareable across programs).

How to revert this?

While this is a practice discouraged by Bottles and we take no responsibility for what may happen after exposing your homedir to the runner, there is a very simple way to do it.

then find the bottle you want to give access to the homedir (e.g. it is called Testing in our case), so move to the userdir:

remove the folders you want to expose (e.g. Documents):

then recreate as symlink (e.g. for Documents):

and this is all!

In v2 we have chosen to adopt our dependency system instead of the usual Winetricks.

What are dependencies?

Dependencies on Bottles are like package dependencies on almost all Linux distributions. Software may require dependencies in order to run and these can be downloaded and installed manually or via our dependency manager who will take care of everything (because each dependency can depend on other dependencies).

Why not Winetricks?

We want to offer a centralized dependency management system. We want to be able to trace those installed in the bottle configuration file to be able to remove them or simply share the bottle with all dependencies listed.

Also, with an internal system it will be easier to install dependencies when an Environment is chosen.For example the Software environment requires vcrun, corefonts and several others. With our system we can install the dependencies at the bottle creation, without exiting the software or using external ones.

Extensibility. Using external repositories for dependencies and providing these with a manifest containing instructions and dependencies, it will be easier to add new dependencies to Bottles and extend support for new software.

Finally, Winetricks is external software and clashes with our UI 😏.

A community driven repository

Wine uses GStreamer to play videos in games. There's a lot of codecs available for developers to encode their videos, and GStreamer needs different plugins for each of those codecs.

Wine versions with bundled GStreamer plugins

Some Wine versions ships their own GStreamer plugins (like Wine-GE, Proton-GE). Bottles will try to use those embedded plugins if they are available by default.

Sometimes, this may cause problems, for example when embedded GStreamer plugins are outdated against your codecs on your system (for example on Arch Linux).

The best way to fix this, is to install on your system all GStreamer plugins (gst-plugins-base, gst-plugins-good, gst-plugins-ugly, gst-plugins-bad, and possibly more), and make the environnment variable BOTTLES_USE_SYSTEM_GSTREAMER=1 available from the bottle or program. Multiple ways exists:

• Run Bottles with the variable: BOTTLES_USE_SYSTEM_GSTREAMER=1 bottles

• Add the environment variable to the bottle

• Add the environment variable to the program using launch parameters

Wine versions without GStreamer plugins

Classic Wine, Caffe, Soda, Vaniglia and most of the Wine versions do not ship any GStreamer plugins. This may cause problems when launching games, as if a GStreamer installation is not found on your system, videos won't play.

Here's an example of a GStreamer plugin missing:

You should install GStreamer, and all plugins that are published by GStreamer. You should look at your distro wiki page about it, but plugins are usually named gst-plugins-base, gst-plugins-good, gst-plugins-ugly, gst-plugins-bad.

Older versions will be deprecated?

We keep the main versions of Bottles actively developed:

Backward compatibility

Thanks to a common model and an internal update system, you can update Bottles without worrying about anything. You can import Bottles v1 prefixes via the built-in importer.

Why a new application?

Bottles was born in 2017 as a personal need. I needed a practical way to manage my wineprefixes. I hate the idea of using applications that install me a version of wine for each application and I decided to create this application, based on the concept of using one or more wine prefixes as a "container" for all my applications.

In 2020 thanks to Valve, we have access to Proton. An optimized version of Wine for gaming. Thanks also to other projects like DXVK/VKD3D/Esync/Fsync/Shader compiler and others, we can run a large set of video games designed for Windows, on Linux.

The idea of creating an environment-based wineprefix manager comes from the standardization of dependencies and parameters necessary to run a game. On the other hand, we have software (often not up to date) that require environments and configurations different from those used in gaming. Hence the idea of managing separate environments.

Why not just POL or Lutris?

Because they are similar but different applications. I want to create environments that contain more applications and games and where the wine version can be updated.

I also want to be able to export my bottles allowing easy sharing, with or without applications. In POL/Lutris we have the concept of "with this version of wine and these changes it works". In Bottles the concept is "this is my wine bottle, I want to install this software".

The goal with this version is also to integrate with the system in the best possible way. Being able to decide in a few bottles to run an .exe/.msi file and have control over it without having to open Bottles for each operation.

Bottles is close to what wineprefix means, since v.2 it provides a simplified method to generate environment-based bottles and thanks to other tools it simplifies the management but nothing more.

Main features

There are some features that make Bottles unique: