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?

It's simple. Start by installing Bottles on your Linux distribution.

First run

Already installed? Let's go with the first boot of Bottles!

The Flatpak package is the only fully sandboxed version. It bundles all the needed dependencies and tools and works on most distributions .

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

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.

Clicking on the Refresh button () will launch a search for wineprefixes available for import.

Button allows you to import bottle backups created earlier (Backups & Duplicate).

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.

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.

Since the , Bottles support the launch programs using links with special Bottles’ protocol. Such links will be recognized by the xdg-open utility and redirected to Bottles to execute certain commands.

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.

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

Steam Flatpak

then restart Bottles.

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:

• a powerful, integrated and written from scratch dependency manager based on a community driven and easy to expand repository

• version control to easily restore a bottle state (goodbye disasters)

• management based on pre-configured environments ready for Gaming or Software, with the most common dependencies pre-installed and an ad hoc configuration to immediately run a lot of software, you can also configure your environment from scratch

• full-sandbox (via Flatpak)

• easy config or full backup export and import, also cloning

• automatically detect installed programs, no need to manually add to the programs list

• 360° customization of the whole environment without having to go through winecfg

• a fully integrated installers manager also based on a community driven repository

and much, much more. Try Bottles to discover all the features we have designed to make it easier for you to run Windows software on Linux!

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).

Read more about, here.

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

Our repository will be community driven. This means that other users can open Pull Requests to provide new dependency support to Bottles!

Online database: https://usebottles.com/database/dependencies

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.

This is one of our most important features in Bottles. It is based on a public and community driven repository where maintainers can propose new dependencies. Read more.

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

You can switch to multiselection mode using the button .

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

Maintainers of dependencies can pack them, read an introduction for packing.

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

In the Graphics section you can set up some graphics related utilities, e.g. you can toggle DXVK, VKD3D, DLSS, FSR, LatencyFleX or choose to use a virtual desktop with a custom resolution or make Bottles use your discrete GPU (for dual-gpu laptops, like optimus, this will improve performances at the cost of increased power usage).

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.

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.

Each installer came with its maintainer review, you can access it from the context menu or from its dedicated page on the apps catalog.

All installers are placed in a public repository where any user can contribute. If you are interested in make your own installers, please read the maintainers documentation.

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.

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.

This magical component takes care of translating instructions from Direct3D 9/10/11 (from Windows) to Vulkan (to Linux) and is developed by doitsujin and many other contributors.

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

Other variables can be found from the official repository and can be set using the "Environment variables" settings in the bottle Preferences ("System" section), like this:

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

In the Runners section you can list, browse and install new runners which can be used to create new bottles. Read more about Runners.

DLL Components

From the DLL Components section you can list, browse and install new versions of DXVK, VKD3D, DXVK-NVAPI and LatencyFleX. Read more about DXVK.

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.

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.

The Bottles Flatpak is sandboxed and confined in its directories. It makes use of portals to let you open and save files in other directories.

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

• let the Importer find windows prefixes from other managers directories;

• 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

or to manage more complex cases through a GUI we can use an external program named Flatseal, it can be easily installed from Flathub using a compatible store like GNOME Software, elementary Appcenter or Discover. It is also possible to install through the command line:

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.

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:

• (our official runner)

• Lutris (from Lutris Developers)

• Proton-GE (from )

• 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 (developed by and improved/offered by in the GE custom version) is a much more complex version of Wine and is suitable for the most modern games.

It contains several patches for specific gaming titles support, implements support and integrates dxvk (installable on wine from the bottle preferences page).

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?

Runners are installed via a community-driven Bottles .

If the runner you are looking for is not present, you can add it yourself by opening a Pull Request in the repository, .

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.

The files we download are available from our for analysis purposes. The latest versions of the following components will be downloaded at the first start:

• 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.

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

Let's go into the details of the bottle of our interest (read here how to create one if you don't have one).

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:

bottles -b bottle_name -e /full/executable/path

bottles -b bottle_name -l /full/lnk/path

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.

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.

If you don't see the program you are looking for, press the Refresh button at the top right () to let Bottles searching for new programs.

Then press the Play button on the right () to start the program.

Add сustom programs

If Bottles cannot find your program automatically, you can manually specify the path to the executable file. To do this, click on the Add button () and select the executable file.

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.

You can switch the display mode of hidden programs using a special button . After switching the display mode, you will be able to see previously hidden programs.

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

If the program does not appear in the list even after the Refresh, it may be that it is installed in a path not monitored by Bottles. Open an issue so that we can identify the path and add it to the list of directories.

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:

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.

From: .

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:

Backtrace from specific process

To receive the backtrace of a specific process, type:

to list all active processes in the wineprefix.

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

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

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

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?

Each when making a new windows prefix (we call these bottles here), creates a similar Windows structure:

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.

First we need to expose the homedir to Bottles, giving it the right permission ( how to achieve this). Once the homedir is exposed, get into a terminal and move to the Bottles flatpak path:

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!

First the basics

All dependencies present in Bottles are placed in a public repository, available here.

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:

vcredist2013:
  Description: Microsoft Visual C++ Redistributable (2013) 12.0
  Category: Essentials
vcreditst2015:
  Description: Microsoft Visual C++ Redistributable (2015)
  Category: Essentials
vcredist2019:
  Description: Microsoft Visual C++ Redistributable (2015-2019) 14.28.29325
  Category: Essentials

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

Each dependency has a manifest that contains some information and instructions for its installation. This is an example from Fonts/allfonts.yml manifest:

Name: allfonts
Description: All Microsoft and Adobe essential fonts
Provider: Various
License: Mostly Microsoft EULA
License_url: https://www.microsoft.com/web/webpi/eula/net_library_eula_enu.htm
Dependencies: []

Steps:
- action: cab_extract
  file_name: arial32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/arial32.exe
  file_checksum: 9637DF0E91703179F0723EC095A36CB5
  
- action: cab_extract
  file_name: arialb32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/arialb32.exe
  file_checksum: C9089AE0C3B3D0D8C4B0A95979BB9FF0
  
- action: cab_extract
  file_name: andale32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/andale32.exe
  file_checksum: CBDC2FDD7D2ED0832795E86A8B9EE19A
  
- action: cab_extract
  file_name: comic32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/comic32.exe
  file_checksum: 2B30DE40BB5E803A0452C7715FC835D1
  
- action: cab_extract
  file_name: courie32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/courie32.exe
  file_checksum: 4E412C772294403AB62FB2D247D85C60
  
- action: cab_extract
  file_name: georgi32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/georgi32.exe
  file_checksum: 4D90016026E2DA447593B41A8D8FA8BD
  
- action: cab_extract
  file_name: impact32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/impact32.exe
  file_checksum: 7907C7DD6684E9BADE91CFF82683D9D7
  
- action: cab_extract
  file_name: times32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/times32.exe
  file_checksum: ED39C8EF91B9FB80F76F702568291BD5
  
- action: cab_extract
  file_name: trebuc32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/trebuc32.exe
  file_checksum: 0D7EA16CAC6261F8513A061FBFCDB2B5
  
- action: cab_extract
  file_name: verdan32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/verdan32.exe
  file_checksum: 12D2A75F8156E10607BE1EAA8E8EF120
  
- action: cab_extract
  file_name: webdin32.exe
  url: https://mirrors.kernel.org/gentoo/distfiles/webdin32.exe
  file_checksum: 230A1D13A365B22815F502EB24D9149B
  
- action: install_cab_fonts
  url: temp/arial32
  fonts: 
   - Ariali.TTF
   - Arialbd.TTF
   - Arialbi.TTF
   - Arial.TTF
  
- action: install_cab_fonts
  url: temp/arialb32
  fonts: 
   - AriBlk.TTF
  
- action: install_cab_fonts
  url: temp/arial32
  fonts: 
   - Ariali.TTF
   - Arialbd.TTF
   - Arialbi.TTF
   - Arial.TTF
  
- action: install_cab_fonts
  url: temp/andale32
  fonts: 
   - AndaleMo.TTF
  
- action: install_cab_fonts
  url: temp/comic32
  fonts: 
   - Comicbd.TTF
   - Comic.TTF
  
- action: install_cab_fonts
  url: temp/courie32
  fonts: 
   - cour.ttf
   - courbd.ttf
   - courbi.ttf
   - couri.ttf
  
- action: install_cab_fonts
  url: temp/georgi32
  fonts: 
   - Georgiaz.TTF
   - Georgiab.TTF
   - Georgiai.TTF
   - Georgia.TTF
  
- action: install_cab_fonts
  url: temp/arial32
  fonts: 
   - Ariali.TTF
   - Arialbd.TTF
   - Arialbi.TTF
   - Arial.TTF
  
- action: install_cab_fonts
  url: temp/impact32
  fonts: 
   - Impact.TTF
  
- action: install_cab_fonts
  url: temp/times32
  fonts: 
   - Times.TTF
   - Timesbd.TTF
   - Timesbi.TTF
   - Timesi.TTF
  
- action: install_cab_fonts
  url: temp/trebuc32
  fonts: 
   - trebuc.ttf
   - Trebucbd.ttf
   - trebucbi.ttf
   - trebucit.ttf
  
- action: install_cab_fonts
  url: temp/verdan32
  fonts: 
   - Verdanab.TTF
   - Verdanai.TTF
   - Verdanaz.TTF
   - Verdana.TTF
  
- action: install_cab_fonts
  url: temp/webdin32
  fonts: 
   - Webdings.TTF

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:

• Filling a new issue following the template for the dependencies implementation request

• Implementing by yourself Read more

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:

for all other packages:

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:

List

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

the -f argument for bottles supports the environment prefix:

while for components the category one can be used:

Programs

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

Tools

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

Reg

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

Edit

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

Add

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

New

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

Run

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

Shell

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

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:

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:

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

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.

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

# make a copy
yes | cp -rf \
~/.local/share/bottles/* \
~/.var/app/com.usebottles.bottles/data/bottles

# or move (using rsync to take care of existing files)
rsync -a \
~/.local/share/bottles/* \
~/.var/app/com.usebottles.bottles/data/bottles

Restart Bottles and that's it.

How to backup

To backup your bottle, just go to the bottle details view and press the button at the top right of your bottle, then select the backup method you prefer.

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

You can also import the backup of a bottle, using our Importer.

These are the shortcuts available in Bottles:

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:

winegstreamer error: decodebin0: Your GStreamer installation is missing a plug-in.
winegstreamer error: decodebin0: ../gst/playback/gstdecodebin2.c(4701): gst_decode_bin_expose (): /GstBin:bin0/GstDecodeBin:decodebin0:
no suitable plugins found:
Missing decoder: Advanced Streaming Format (ASF) (video/x-ms-asf)

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.