Bottles

https://docs.usebottles.com
Admin
Bottles is an application that allows you to easily manage Windows prefixes on your favorite Linux...
Tokens:22,915
Snippets:207
Trust Score:9.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run program with custom wine command

Source: https://docs.usebottles.com/advanced/use-bottles-as-wine-command.md

Usage example: run a program or installer with the custom wine command, which uses the chosen bottle.

```shell
wine program_name.exe # or installer_name.msi
```

--------------------------------

### Install Bottles Beta via Flathub

Source: https://docs.usebottles.com/getting-started/installation.md

Commands to add the Flathub beta remote and install the Bottles beta package.

```bash
flatpak remote-add --user flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo
flatpak update --appstream
```

```bash
flatpak install --user flathub-beta com.usebottles.bottles
```

--------------------------------

### Build Bottles from Source

Source: https://docs.usebottles.com/getting-started/installation.md

Commands to build the application using flatpak-builder and install the resulting package.

```bash
flatpak-builder --repo=bottles --force-clean --user build-dir com.usebottles.bottles.yml
flatpak remote-add --user bottles bottles --no-gpg-verify
flatpak install --user bottles com.usebottles.bottles
```

--------------------------------

### Launch CLI with Flatpak

Source: https://docs.usebottles.com/advanced/cli.md

Launch the Bottles CLI using Flatpak, the suggested installation method. The --help flag shows available subcommands and options.

```bash
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
```

--------------------------------

### Run Bottles

Source: https://docs.usebottles.com/getting-started/installation.md

Command to launch the installed Bottles application.

```bash
flatpak run com.usebottles.bottles
```

--------------------------------

### HTTP GET request to ask documentation

Source: https://docs.usebottles.com/bottles/versioning.md

Perform an HTTP GET request on the documentation index with the 'ask' parameter and optional 'goal' parameter to get a direct answer. The 'ask' parameter is the immediate question, and 'goal' describes the broader end goal.

```http
GET https://docs.usebottles.com/bottles/versioning.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### Programs interface help

Source: https://docs.usebottles.com/advanced/cli.md

Shows the usage for the programs interface, which lists all programs in a bottle (only those added by users or installers).

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

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

--------------------------------

### Launch CLI for other packages

Source: https://docs.usebottles.com/advanced/cli.md

Launch the Bottles CLI for non-Flatpak installations.

```bash
bottles-cli --help
```

--------------------------------

### Create custom wine command (Flatpak)

Source: https://docs.usebottles.com/advanced/use-bottles-as-wine-command.md

Shell script for Flatpak installations. Place in ~/.local/bin or any PATH directory. Replace MyBottle with your bottle name. Requires no system wine installed.

```shell
#!/bin/sh
flatpak run --command='bottles-cli' com.usebottles.bottles run -b MyBottle -e "$@"
```

--------------------------------

### GStreamer missing plugin error example

Source: https://docs.usebottles.com/faq/video-gstreamer-problems.md

Example error output when a GStreamer plugin is missing, showing the decodebin0 error and missing decoder for ASF.

```text
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)
```

--------------------------------

### Install Flatseal for GUI permission management

Source: https://docs.usebottles.com/flatpak/expose-directories.md

Install Flatseal, a GUI tool for managing Flatpak permissions, from Flathub. After installation, launch Flatseal, select Bottles from the left menu, and navigate to the Filesystem section to configure directory access.

```bash
flatpak install flathub com.github.tchx84.Flatseal
```

--------------------------------

### index.yml dependency index example

Source: https://docs.usebottles.com/contribute/missing-dependencies.md

Shows the structure of the index.yml file, where each dependency is listed by its name with a description and the category it belongs to. Use this as a reference when adding new dependencies to the repository index.

```yaml
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
```

--------------------------------

### Create custom wine command (non-Flatpak)

Source: https://docs.usebottles.com/advanced/use-bottles-as-wine-command.md

Alternative shell script for non-Flatpak installations. Place in ~/.local/bin or any PATH directory. Replace MyBottle with your bottle name.

```shell
#!/bin/sh
bottles-cli  run -b MyBottle -e "$@"
```

--------------------------------

### Launch executables from CLI: bottles -b bottle_name -e/-l

Source: https://docs.usebottles.com/bottles/run-.exe-.msi-.bat-.lnk-files

Use these CLI commands to launch executables without showing the Bottles GUI. The first command runs .exe/.msi/.bat files by passing the executable path with -e; the second runs .lnk files using -l. Both require the bottle name via -b. For flatpak installations, replace 'bottles' with 'flatpak run com.usebottles.bottles'.

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

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

--------------------------------

### Run Bottles AppImage from terminal to capture logs

Source: https://docs.usebottles.com/utilities/logs-and-debugger.md

Start Bottles from a system terminal to capture all Bottles and wineprefix logs. The terminal must remain open to receive the logs.

```bash
cd /path_to_appimage
./Bottles*.AppImage
```

--------------------------------

### Tools interface help

Source: https://docs.usebottles.com/advanced/cli.md

Shows the usage for the tools interface, which launches any WINE utility.

```bash
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
```

--------------------------------

### bottles-cli --json programs -b MyBottle

Source: https://docs.usebottles.com/advanced/cli.md

Lists programs in a bottle with --json, returning more info than the classic launch, including executable, arguments, name, path, folder, icon, script, and removed fields.

```bash
bottles-cli --json programs -b MyBottle
```

```json
[{"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}]
```

--------------------------------

### Get backtrace for all running processes in winedbg

Source: https://docs.usebottles.com/utilities/logs-and-debugger.md

Type this command in the Wine debugger to get the backtrace of all running processes in the wineprefix.

```bash
bt all
```

--------------------------------

### bottles-cli programs

Source: https://docs.usebottles.com/advanced/cli.md

Lists all programs in a specified bottle (only those added by users or installers).

```APIDOC
## bottles-cli programs

### Description
Lists all programs in a specified bottle (only those added by users or installers).

### Method
CLI

### Endpoint
bottles-cli programs

### Parameters
#### Required Arguments
- `-b BOTTLE, --bottle BOTTLE` - Required - Bottle name

#### Optional Arguments
- `-h, --help` - Optional - Show help message and exit

### Request Example
```
bottles-cli programs -b mybottle
```

### Response
#### Success Response
Returns a list of programs in the specified bottle.

#### Response Example
```
(Output depends on the programs)
```
```

--------------------------------

### Run Bottles with BOTTLES_USE_SYSTEM_GSTREAMER=1

Source: https://docs.usebottles.com/faq/video-gstreamer-problems.md

Launch Bottles with the environment variable to force using system GStreamer plugins instead of bundled ones.

```bash
BOTTLES_USE_SYSTEM_GSTREAMER=1 bottles
```

--------------------------------

### Info interface help

Source: https://docs.usebottles.com/advanced/cli.md

Shows the usage for the info interface, which provides access to Bottles information.

```bash
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
```

--------------------------------

### bottles-cli --help

Source: https://docs.usebottles.com/advanced/cli.md

Displays the main help for the Bottles CLI, listing all available subcommands and global options.

```APIDOC
## bottles-cli --help

### Description
Displays the main help for the Bottles CLI, listing all available subcommands and global options.

### Method
CLI

### Endpoint
bottles-cli

### Parameters
#### Global Options
- `-h, --help` - Optional - Show help message and exit
- `-v, --version` - Optional - Show program's version number and exit
- `-j, --json` - Optional - Outputs in JSON format

### Request Example
```
bottles-cli --help
```

### Response
#### Success Response
Displays the help text with subcommands: info, list, programs, tools, reg, edit, new, run.

#### Response Example
```
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
```
```

--------------------------------

### Flatpak override for desktop entries

Source: https://docs.usebottles.com/bottles/programs.md

Required for the Flatpak version of Bottles to generate desktop entries. Run this command in a terminal after closing Bottles, then start Bottles again.

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

--------------------------------

### Flatpak overrides for Steam shortcuts

Source: https://docs.usebottles.com/bottles/programs.md

Required for the Flatpak version of Bottles to add shortcuts to Steam. Run these commands in a terminal after closing Bottles, then start Bottles again.

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

--------------------------------

### Grant Bottles access to Steam path

Source: https://docs.usebottles.com/flatpak/cant-enable-steam-proton-manager.md

Use these commands to grant Bottles access to the Steam directory, depending on whether Steam is installed as a non-Flatpak or Flatpak application.

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

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

--------------------------------

### bottles-cli add

Source: https://docs.usebottles.com/advanced/cli.md

Adds a new program to a bottle with optional launch options and DXVK/VKD3D/Nvapi toggles.

```APIDOC
## bottles-cli add

### Description
Adds a new program to a bottle with optional launch options and DXVK/VKD3D/Nvapi toggles.

### Usage

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


### Parameters
- **-b, --bottle** (string) - Required - Bottle name
- **-n, --name** (string) - Required - Program name
- **-p, --path** (string) - Required - Program path
- **-l, --launch-options** (string) - Optional - Program launch options
- **--no-dxvk** (flag) - Optional - Disable DXVK for the program
- **--no-vkd3d** (flag) - Optional - Disable VKD3D for the program
- **--no-dxvk-nvapi** (flag) - Optional - Disable DXVK Nvapi for the program

### Example

bottles-cli add -b mybottle -n "My Game" -p "/path/to/game.exe" --no-dxvk


```

--------------------------------

### bottles-cli new usage

Source: https://docs.usebottles.com/advanced/cli.md

Shows the CLI usage for the `new` interface, which creates a new bottle. Requires `--bottle-name` and `--environment` (gaming, application, or custom). Optional flags set architecture, runner, DXVK, VKD3D, DXVK-Nvapi, LatencyFleX, or a custom environment file.

```text
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

```

--------------------------------

### bottles-cli new

Source: https://docs.usebottles.com/advanced/cli.md

Creates a new bottle with specified environment, architecture, and component versions.

```APIDOC
## bottles-cli new

### Description
Creates a new bottle with specified environment, architecture, and component versions.

### Usage

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]


### Parameters
- **--bottle-name** (string) - Required - Bottle name
- **--environment** (string) - Required - Environment to apply (gaming|application|custom)
- **--custom-environment** (string) - Optional - Path to a custom environment.yml file
- **--arch** (string) - Optional - Architecture (win32|win64)
- **--runner** (string) - Optional - Name of the runner to be used
- **--dxvk** (string) - Optional - Name of the dxvk to be used
- **--vkd3d** (string) - Optional - Name of the vkd3d to be used
- **--nvapi** (string) - Optional - Name of the dxvk-nvapi to be used
- **--latencyflex** (string) - Optional - Name of the latencyflex to be used

### Example

bottles-cli new --bottle-name mybottle --environment gaming --arch win64


```

--------------------------------

### bottles-cli edit usage

Source: https://docs.usebottles.com/advanced/cli.md

Shows the CLI usage for the `edit` interface, which modifies an existing bottle's parameters, environment variables, Windows version, runner, DXVK, VKD3D, DXVK-Nvapi, or LatencyFleX. The `-b`/`--bottle` argument is required. Each option accepts a value, with examples provided in the help text.

```text
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')

```

--------------------------------

### Custom launch options with %command% placeholder

Source: https://docs.usebottles.com/bottles/programs.md

Use the %command% placeholder in Launch Options to add custom prefixes and suffixes to the executable command. The placeholder is replaced by the actual command when the program is launched.

```bash
my_command %command% -flag1 -flag2
```

--------------------------------

### bottles-cli tools

Source: https://docs.usebottles.com/advanced/cli.md

Launches any WINE utility for a specified bottle.

```APIDOC
## bottles-cli tools

### Description
Launches any WINE utility for a specified bottle.

### Method
CLI

### Endpoint
bottles-cli tools

### Parameters
#### Positional Arguments
- `{cmd,winecfg,uninstaller,regedit,taskmgr,control,explorer}` - Required - Tool to launch

#### Required Arguments
- `-b BOTTLE, --bottle BOTTLE` - Required - Bottle name

#### Optional Arguments
- `-h, --help` - Optional - Show help message and exit

### Request Example
```
bottles-cli tools -b mybottle winecfg
```

### Response
#### Success Response
Launches the specified WINE tool.

#### Response Example
```
(No output, tool launches)
```
```

--------------------------------

### bottles-cli run

Source: https://docs.usebottles.com/advanced/cli.md

Launches an executable from a given path or any program in a bottle using its name.

```APIDOC
## bottles-cli run

### Description
Launches an executable from a given path or any program in a bottle using its name.

### Usage

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


### Parameters
- **-b, --bottle** (string) - Required - Bottle name
- **-e, --executable** (string) - Optional - Path to the executable
- **-a, --args** (string) - Optional - Arguments to pass to the executable
- **-p, --program** (string) - Optional - Program to run

### Example

bottles-cli run -b mybottle -e "/path/to/game.exe" -a "--fullscreen"


```

--------------------------------

### bottles-cli run usage

Source: https://docs.usebottles.com/advanced/cli.md

Shows the CLI usage for the `run` interface, which launches an executable from a given path or a program by name in a bottle. Requires `-b`/`--bottle`. Use `-e`/`--executable` with a path, `-a`/`--args` for arguments, or `-p`/`--program` to run a known program.

```text
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

```

--------------------------------

### List interface help

Source: https://docs.usebottles.com/advanced/cli.md

Shows the usage for the list command, used for listing Bottles entities. The -f/--filter option filters bottles and components.

```bash
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')
```

--------------------------------

### Copy or move bottles to Flatpak data directory

Source: https://docs.usebottles.com/flatpak/migrate-bottles-to-flatpak.md

Use these commands to migrate your bottles from ~/.local/share/bottles to ~/.var/app/com.usebottles.bottles/data/bottles. The first command copies with cp, the second moves with rsync. Restart Bottles after migration.

```bash
# 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
```

--------------------------------

### Expose system home to Bottles

Source: https://docs.usebottles.com/flatpak/expose-directories/use-system-home.md

Commands to expose the system home directory to a Bottles Flatpak application by replacing sandboxed folders with symlinks.

```text
._ bottles/
    |_ your_bottle/
        |_ bottle.yml
        |_ drive_c/
            |_ ProgramData/
            |_ Program Files/
            |_ Program Files (x86)/
            |_ users/
                |_ Public/
                |_ your_username/
            |_ windows/

```

```text
..
    |_ users/
        |_ mirko
            |_ AppData
            |_ Contacts
            |_ Desktop -> ~/Desktop
            |_ Videos -> ~/Videos

```

```bash
cd ~/.var/app/com.usebottles.bottles/data/bottles/bottles

```

```bash
cd Testing/drive_c/users/your_username/ && ls -l

```

```bash
rm -r Documents

```

```bash
ln -s ~/Documents Documents

```

--------------------------------

### bottles-cli add usage

Source: https://docs.usebottles.com/advanced/cli.md

Shows the CLI usage for the `add` interface, which adds a new program to a bottle. Requires `-b`/`--bottle`, `-n`/`--name`, and `-p`/`--path`. Optional flags disable DXVK, VKD3D, or DXVK-Nvapi for the program.

```text
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

```
Tokens:
Raw