BitComet Installation Guide for Linux

BitComet Linux Edition is available as AppImage, Flatpak, and deb packages, as well as Docker images.

AppImage package

The AppImage package can run the application without needing superuser permissions to install it. The detailed info about AppImage format can be found at https://www.appimage.org/

• Step 1: Check Linux Distro Version (optional)

Linux Distro	Supported Version
Ubuntu	18.04
Debian	12.1
Fedora	38
openSUSE	Leap 15.5 / Tumbleweed
CentOS	Stream 9
Others	GLIBCXX_3.4.22 or higher

The only requirement to run BitComet in your Linux distro is the GLIBCXX version in libstdc++.so.
BitComet cannot run if the GLIBCXX version in your Linux distro is lower than GLIBCXX_3.4.22

The version of installed GLIBCXX in your Linux distro can be find by following commands:

# find libstdc++.so.6 file
find /usr/ -name libstdc++.so.6

# get GLIBCXX version, typically using
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX

# or using
strings /usr/lib64/libstdc++.so.6 | grep GLIBCXX

• Step 2: Download BitComet

The AppImage file of BitComet Linux edition can be downloaded from the official website.

• Step 3: Make AppImage executable and run it

Using the GUI

1. Open your file manager and browse to the location of the AppImage
2. Right-click on the AppImage and click the ‘Properties’ entry
3. Switch to the Permissions tab and click the ‘Allow executing file as program’ checkbox
4. Close the dialog
5. Double-click on the AppImage file to run

Using the Terminal

1. Open a terminal
2. Change to the directory containing the AppImage, for example:

cd <my directory>

1. Make the AppImage executable:

chmod +x BitComet.AppImage

1. Run the AppImage:

./BitComet.AppImage

• Step 4: Install missing libraries if failed to run AppImage (distro-specific)

If your Linux distro doesn't contain some necessary libraries that BitComet depends on, please try to install them manually.

1. Open a terminal
2. Change to the directory containing the AppImage, for example:

cd <my directory>

1. Try to run the AppImage again:

./BitComet.AppImage

1. Install the missing libraries based on the error message:

For Ubuntu / Debian distros

Library	commands to check installed version and install missing library
libfuse2	apt list | grep libfuse sudo apt install libfuse2
libwebkit2gtk-4.0	apt list | grep libwebkit2gtk sudo apt install libwebkit2gtk-4.0-37

Note: For Ubuntu 24.04 and above distros, the apt sources for 22.04 are required.

sudo nano /etc/apt/sources.list.d/ubuntu.sources
# add "jammy" to the end of line "Suites: xxx xxx xxx"
# add "jammy-security" to the end of line "Suites: xxx-security"
# save and quit
sudo apt update
sudo apt install libwebkit2gtk-4.0-37
# revert apt sources if necessary

For Fedora / RedHat / CentOS distros

Library	commands to check installed version and install missing library
libfuse2	yum list fuse* sudo yum --enablerepo=epel install fuse-sshfs sudo usermod -a -G fuse $(whoami)
libwebkit2gtk-4.0	yum list webkit2gtk* sudo yum install webkit2gtk-4.0.x86_64

For openSUSE distros

Library	commands to check installed version and install missing library
libfuse2	zypper search -i libfuse sudo zypper install fuse libfuse2
libwebkit2gtk-4.0	zypper search -i webkit2gtk sudo zypper install webkit2gtk-4_0-37

More info about errors related to something called “FUSE” can be found at this page

Flatpak package

BitComet provides a Flatpak package starting with version 2.22.0. The package is currently available for x86_64 Linux systems only. ARM64, LoongArch, and other architectures cannot install this package directly.

• Step 1: Install Flatpak

Ubuntu / Debian

sudo apt update
sudo apt install flatpak

Linux Mint usually includes Flatpak by default. If the flatpak command is unavailable, use the Ubuntu / Debian commands above.

Fedora

Fedora Workstation usually includes Flatpak by default. If it is not installed, run:

sudo dnf install flatpak

Arch Linux / Manjaro

sudo pacman -S flatpak

openSUSE Leap / Tumbleweed

sudo zypper install flatpak

After installing Flatpak, logging out and back in is recommended so that the desktop environment can load the application menu entry and other desktop integration. This is usually unnecessary if you only run BitComet from the command line.

• Step 2: Add Flathub

Add Flathub for the current user:

flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

You can confirm that Flathub is configured with:

flatpak remotes --user

• Step 3: Download and install BitComet

Download BitComet-x.y.z-x86_64.flatpak from the official website, open a terminal in the directory containing the downloaded file, and run:

flatpak install --user ./BitComet-x.y.z-x86_64.flatpak

Do not add --no-deps for a first-time installation. Flatpak downloads the required org.gnome.Platform//50 runtime from Flathub automatically. The runtime may require several hundred MB of storage, but it can be shared with other Flatpak applications installed by the same user.

• Step 4: Run BitComet

After installation, launch BitComet from the application menu or run:

flatpak run com.bitcomet.BitComet

• Installing a new version

Download the new .flatpak file and run the installation command again, replacing x.y.z with its version number:

flatpak install --user ./BitComet-x.y.z-x86_64.flatpak

The BitComet package is distributed as a local single-file bundle, so the application itself is not updated from Flathub by flatpak update. Flatpak can still update its Flathub-provided runtimes:

flatpak update --user

• View information and permissions

flatpak info com.bitcomet.BitComet
flatpak info --show-permissions com.bitcomet.BitComet

The sandbox allows network access, audio, Wayland/X11 display, desktop notifications, GPU acceleration, and access to the user's Downloads directory. Other filesystem locations are not available by default.

• Uninstall BitComet

flatpak uninstall --user com.bitcomet.BitComet

To remove runtimes that are no longer used by any user-installed Flatpak application, run:

flatpak uninstall --user --unused

Troubleshooting

BitComet does not appear in the application menu

Log out and back in, then confirm that BitComet is installed:

flatpak list --app --user

You can run flatpak run com.bitcomet.BitComet even if the application menu has not been refreshed.

Flatpak cannot find org.gnome.Platform//50

Confirm that Flathub is configured for the current user, then install the runtime manually:

flatpak remotes --user
flatpak install --user flathub org.gnome.Platform//50

Then run the BitComet installation command again.

The Downloads directory is empty in the file chooser

Flatpak uses the XDG user directory configuration to locate the host system's Downloads directory. Check the current setting with:

xdg-user-dir DOWNLOAD

If it does not point to the correct Downloads directory, install xdg-user-dirs, update the setting, and restart BitComet. The package intentionally uses the standard XDG Downloads directory so that it works with different user names and Linux distributions.

Deb package

• Step 1: Download BitComet

the deb package of BitComet Linux edition can be downloaded from official website.

• Step 2: Install deb package

1. Open a terminal
2. Change to the directory containing the deb file, for example:

cd <my directory>

1. Install the deb package:

sudo apt install ./BitComet-2.12.0-x86_64.deb

• Step 3: Start the program

Launch the main program in GUI mode:

BitComet

Launch the main program in console mode with Web UI:

bitcometd

Note: The main program in both modes can only run one instance at a time.

Docker image (GUI mode)

The GUI image provides the BitComet GTK interface through a browser. It supports linux/amd64 and linux/arm64. Image tags and additional details are available on Docker Hub.

The browser GUI requires HTTPS Web Authentication. Native VNC is optional and port 5900 is not exposed by default. The optional BitComet WebUI uses its own credentials configured inside BitComet; it does not share the browser GUI credentials.

Deploy with Docker Compose

Set the browser GUI password in the shell or in a .env file. Do not commit a real password to a repository:

export BITCOMET_GUI_PASSWORD='replace-with-a-strong-password'

Save the following as docker-compose.yml. Replace the host paths before the colon with directories suitable for your system:

services:
  bitcomet:
    container_name: bitcomet
    image: wxhere/bitcomet:latest
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      # BitComet configuration and GUI state.
      - /docker/appdata/BitComet:/config:rw

      # Downloaded files.
      - /home/user/Downloads:/output:rw
    ports:
      # Browser GUI: https://HOST:6080
      - "6080:5800"

      # Optional BitComet WebUI. Remove this mapping and
      # BITCOMET_WEBUI_PORT below when WebUI access is not needed.
      - "6081:8080"

      # BitTorrent incoming and DHT ports.
      - "6082:6082/tcp"
      - "6082:6082/udp"
    environment:
      # These values control the application process and volume permissions,
      # not authentication. Change them only when host ownership differs.
      USER_ID: "1000"
      GROUP_ID: "1000"

      # Optional browser desktop size.
      DISPLAY_WIDTH: "1280"
      DISPLAY_HEIGHT: "768"

      WEB_AUTHENTICATION_USERNAME: "bitcomet"
      WEB_AUTHENTICATION_PASSWORD: "${BITCOMET_GUI_PASSWORD:?BITCOMET_GUI_PASSWORD is required}"

      # Optional BitComet WebUI internal port.
      BITCOMET_WEBUI_PORT: "8080"

      # Internal BitTorrent listening port.
      BITCOMET_BT_PORT: "6082"

      # Set only for migration from v2.22.0 or earlier when old tasks
      # store this exact absolute container path.
      # LEGACY_DOWNLOAD_PATH: "/home/sandbox/Downloads"

Start the container:

docker compose up -d

Open https://HOST:6080 and log in with bitcomet and the password supplied through BITCOMET_GUI_PASSWORD. A browser warning may appear because the container generates a self-signed HTTPS certificate. If the optional BitComet WebUI is enabled, open http://HOST:6081 and use the independent credentials configured in BitComet.

Deploy with Docker CLI

Set the password first. Make sure the host directories used by the volume mappings are writable by the configured USER_ID and GROUP_ID:

export BITCOMET_GUI_PASSWORD='replace-with-a-strong-password'

Run the container:

docker run -d \
  --name bitcomet \
  --restart unless-stopped \
  --ulimit nofile=65536:65536 \
  -v /docker/appdata/BitComet:/config:rw \
  -v "$HOME/Downloads":/output:rw \
  -p 6080:5800 \
  -p 6081:8080 \
  -p 6082:6082/tcp \
  -p 6082:6082/udp \
  -e USER_ID=1000 \
  -e GROUP_ID=1000 \
  -e DISPLAY_WIDTH=1280 \
  -e DISPLAY_HEIGHT=768 \
  -e WEB_AUTHENTICATION_USERNAME=bitcomet \
  -e WEB_AUTHENTICATION_PASSWORD="$BITCOMET_GUI_PASSWORD" \
  -e BITCOMET_WEBUI_PORT=8080 \
  -e BITCOMET_BT_PORT=6082 \
  wxhere/bitcomet:latest

If the optional BitComet WebUI is not needed, remove -p 6081:8080 and -e BITCOMET_WEBUI_PORT=8080. Production deployments should prefer the immutable wxhere/bitcomet:v2.23.0 tag for predictable rollback.

Upgrade from v2.22.0 or earlier

Stop the old container and back up the host configuration directory before upgrading. Keep the host paths on the left side of each volume mapping, but change the container targets to /config and /output.

If an old task stores an absolute container download path such as /home/sandbox/Downloads, add the actual old path to the environment:

LEGACY_DOWNLOAD_PATH: "/home/sandbox/Downloads"

For Docker CLI, add -e LEGACY_DOWNLOAD_PATH=/home/sandbox/Downloads. The old image allowed a custom Linux username, so use the exact path shown in the old task properties instead of assuming that the username is sandbox. Do not set this variable for a new installation or when existing tasks already use /output. The image does not scan or rewrite task data.

Docker image (WebUI-only mode)

The WebUI-only image runs BitComet without a Linux desktop, X server, VNC, or noVNC. It supports linux/amd64 and linux/arm64. Image tags and additional details are available on Docker Hub.

Deploy with Docker Compose

Set the independent BitComet WebUI credentials in the shell or in a .env file:

export BITCOMET_WEBUI_USERNAME='bitcomet'
export BITCOMET_WEBUI_PASSWORD='replace-with-a-strong-password'

Save the following as docker-compose.yml:

services:
  bitcomet-webui:
    container_name: bitcomet-webui
    image: wxhere/bitcomet-webui:latest
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      # BitComet configuration files.
      - /docker/appdata/BitComet:/config:rw

      # Downloaded files.
      - /home/user/Downloads:/output:rw
    ports:
      # BitComet WebUI.
      - "7080:8080"

      # BitTorrent incoming and DHT ports.
      - "7082:6082/tcp"
      - "7082:6082/udp"
    environment:
      # These values control process identity and volume permissions,
      # not authentication.
      USER_ID: "1000"
      GROUP_ID: "1000"

      # Internal container ports.
      BITCOMET_WEBUI_PORT: "8080"
      BITCOMET_BT_PORT: "6082"

      WEBUI_USERNAME: "${BITCOMET_WEBUI_USERNAME:-bitcomet}"
      WEBUI_PASSWORD: "${BITCOMET_WEBUI_PASSWORD:?BITCOMET_WEBUI_PASSWORD is required}"

      # Set only for migration from a v2.22.0-or-earlier WebUI-only image
      # when old tasks store this exact absolute container path.
      # LEGACY_DOWNLOAD_PATH: "/root/Downloads"

Start the container and open http://HOST:7080:

docker compose up -d

Deploy with Docker CLI

Set the credentials first. Make sure the host directories used by the volume mappings are writable by the configured USER_ID and GROUP_ID:

export BITCOMET_WEBUI_USERNAME='bitcomet'
export BITCOMET_WEBUI_PASSWORD='replace-with-a-strong-password'

Run the container:

docker run -d \
  --name bitcomet-webui \
  --restart unless-stopped \
  --ulimit nofile=65536:65536 \
  -v /docker/appdata/BitComet:/config:rw \
  -v "$HOME/Downloads":/output:rw \
  -p 7080:8080 \
  -p 7082:6082/tcp \
  -p 7082:6082/udp \
  -e USER_ID=1000 \
  -e GROUP_ID=1000 \
  -e BITCOMET_WEBUI_PORT=8080 \
  -e BITCOMET_BT_PORT=6082 \
  -e WEBUI_USERNAME="$BITCOMET_WEBUI_USERNAME" \
  -e WEBUI_PASSWORD="$BITCOMET_WEBUI_PASSWORD" \
  wxhere/bitcomet-webui:latest

Production deployments should prefer the immutable wxhere/bitcomet-webui:v2.23.0 tag for predictable rollback.

Upgrade from v2.22.0 or earlier

Stop the old container and back up the host configuration directory. Keep the host paths unchanged and update the container volume targets from /root/.config/BitComet and /root/Downloads to /config and /output.

Only when old tasks still store /root/Downloads or another old absolute container path, add the actual path:

LEGACY_DOWNLOAD_PATH: "/root/Downloads"

For Docker CLI, add -e LEGACY_DOWNLOAD_PATH=/root/Downloads. Do not set this variable for new installations or upgrades between newer images. Confirm the old tasks, files, WebUI login, and BT/DHT ports before deleting the old container or image.