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)

List of BitComet Docker images in GUI mode: https://hub.docker.com/r/wxhere/bitcomet/tags

Deploy Method 1: using docker-compose

• Step 1: Save docker-compose.yml to your local system:

services:
    sandbox:
        container_name: bitcomet
        image: wxhere/bitcomet:latest
        ulimits:
          nofile:
            soft: 65536
            hard: 65536
        volumes:
            # Store BitComet configuration files on the host.
            - /docker/appdata/BitComet:/home/sandbox/.config/BitComet:rw
            # Store downloaded files on the host.
            - ~/Downloads:/home/sandbox/Downloads:rw
        ports:
            # VNC GUI port
            - 5900:5900
            # Web GUI port
            - 6080:80
            # BitTorrent ports
            - 6082:6082
            - 6082:6082/udp
        environment:
            - VNC_PASSWORD=123456
            - HTTP_PASSWORD=123456
            - USER=sandbox
            - PASSWORD=123456

Note: Please change the username, password, and port mapping according to your own needs.

• Step 2: Pull the docker image, create a container and run it:

docker-compose -f docker-compose.yml up

• Step 3: Open the webpage of BitComet GUI in your browser:

http://127.0.0.1:6080
username: sandbox
password: 123456

or connect to the VNC desktop with your VNC client:

port: 5900
username: sandbox
password: 123456

• Step 4: Click the BitComet icon in desktop to launch it if closed.

Deploy Method 2: using Docker CLI

• Step 1: Pull the docker image:

docker pull wxhere/bitcomet:latest

• Step 2: Create a container and run it:

docker run -d \
  --name=bitcomet \
  --ulimit nofile=65536:65536 \
  -e VNC_PASSWORD=123456 \
  -e HTTP_PASSWORD=123456 \
  -e USER=sandbox \
  -e PASSWORD=123456 \
  -p 5900:5900 \
  -p 6080:80 \
  -p 6082:6082 \
  -p 6082:6082/udp \
  -v /docker/appdata/BitComet:/home/sandbox/.config/BitComet:rw \
  -v ~/Downloads:/home/sandbox/Downloads:rw \
  --restart unless-stopped \
  wxhere/bitcomet:latest

Note: Please change the username, password, and port mapping according to your own needs.

• Step 3: Open the webpage of BitComet GUI in your browser:

http://127.0.0.1:6080
username: sandbox
password: 123456

or connect to the VNC desktop with your VNC client:

port: 5900
username: sandbox
password: 123456

• Step 4: Click the BitComet icon in desktop to launch it if closed.

Docker image (Web UI mode)

List of BitComet Docker images in Web UI mode: https://hub.docker.com/r/wxhere/bitcomet-webui/tags

Deploy Method 1: using docker-compose

• Step 1: Save docker-compose.yml to your local system:

services:
    sandbox:
        container_name: bitcomet-webui
        image: wxhere/bitcomet-webui:latest
        ulimits:
          nofile:
            soft: 65536
            hard: 65536
        volumes:
            # Store BitComet configuration files on the host.
            - /docker/appdata/BitComet:/root/.config/BitComet:rw
            # Store downloaded files on the host.
            - ~/Downloads:/root/Downloads:rw
        ports:
            # BitComet WebUI port
            - 6080:80
            # BitTorrent ports
            - 6082:6082
            - 6082:6082/udp
        environment:
            - BITCOMET_WEBUI_PORT=8080
            - BITCOMET_BT_PORT=6082
            - WEBUI_USERNAME=test
            - WEBUI_PASSWORD=test

Note: Please change the username, password, and port mapping according to your own needs.

• Step 2: Pull the docker image, create a container and run it:

docker-compose -f docker-compose.yml up

• Step 3: Open the webpage of BitComet Web UI in your browser:

http://127.0.0.1:6080
username: test
password: test

Deploy Method 2: using Docker CLI

• Step 1: Pull the docker image:

docker pull wxhere/bitcomet-webui:latest

• Step 2: Create a container and run it:

docker run -d \
  --name=bitcomet-webui \
  --ulimit nofile=65536:65536 \
  -e BITCOMET_WEBUI_PORT=8080 \
  -e BITCOMET_BT_PORT=6082 \
  -e WEBUI_USERNAME=test \
  -e WEBUI_PASSWORD=test \
  -p 6080:80 \
  -p 6082:6082 \
  -p 6082:6082/udp \
  -v /docker/appdata/BitComet:/root/.config/BitComet:rw \
  -v ~/Downloads:/root/Downloads:rw \
  --restart unless-stopped \
  wxhere/bitcomet-webui:latest

Note: Please change the username, password, and port mapping according to your own needs.

• Step 3: Open the webpage of BitComet Web UI in your browser:

http://127.0.0.1:6080
username: test
password: test