Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/torbox-app/torbox-media-center/llms.txt

Use this file to discover all available pages before exploring further.

You can run TorBox Media Center directly on your system using Python, without Docker. This method gives you more control but requires manual setup.

​
Prerequisites

  • Python 3.6 or newer
  • Git (optional, for cloning the repository)
  • A TorBox account on a paid plan (sign up here)
  • Your TorBox API key from settings
  • Linux/Unix/BSD/MacOS for FUSE support (STRM works on all platforms including Windows)

​
Installation

1

Download the source code

Clone the repository using Git:
git clone https://github.com/TorBox-App/torbox-media-center.git
cd torbox-media-center
Or download the ZIP file from GitHub and extract it:
unzip torbox-media-center-main.zip
cd torbox-media-center-main
2

Create environment file

Create a .env file for your configuration:
cp .env.example .env
Or create a new .env file manually:
touch .env
3

Configure environment variables

Edit the .env file and add your configuration:
TORBOX_API_KEY=your_api_key_here
MOUNT_METHOD=strm
MOUNT_PATH=/home/yourusername/torbox
MOUNT_REFRESH_TIME=normal
ENABLE_METADATA=false
RAW_MODE=false
  • Replace your_api_key_here with your actual API key from torbox.app/settings
  • Set MOUNT_PATH to an existing directory where you want your media accessible
  • Choose strm or fuse for MOUNT_METHOD
4

Install Python dependencies

Install all required packages from requirements.txt:
pip3 install -r requirements.txt
This will install:
  • apscheduler - Task scheduling
  • tinydb - Lightweight database
  • httpx - HTTP client
  • python-dotenv - Environment variable management
  • parse-torrent-title - Media metadata parsing
  • fuse-python - FUSE filesystem support (Linux only)
  • GitPython - Git operations
On Windows, FUSE support is not available. Use MOUNT_METHOD=strm instead.
On macOS, FUSE requires macFUSE to be installed separately.
5

Create mount directory

Ensure the mount path exists and is accessible:
mkdir -p ~/torbox
Make sure the user running the script has write permissions:
chmod 755 ~/torbox
6

Run the application

Start TorBox Media Center:
python3 main.py
The application will:
  • Validate your API key
  • Connect to TorBox services
  • Begin syncing your media files
  • Keep running in the foreground
Keep the terminal window open. Closing it will stop the application.

​
Running in the background

To keep TorBox Media Center running after closing your terminal:

​
Using nohup

nohup python3 main.py &

​
Using screen

screen -S torbox
python3 main.py
# Press Ctrl+A then D to detach
Reattach with: 
screen -r torbox

​
Using systemd (Linux)

Create a systemd service file:
/etc/systemd/system/torbox-media-center.service
[Unit]
Description=TorBox Media Center
After=network.target

[Service]
Type=simple
User=yourusername
WorkingDirectory=/path/to/torbox-media-center
ExecStart=/usr/bin/python3 /path/to/torbox-media-center/main.py
Restart=always

[Install]
WantedBy=multi-user.target
Enable and start the service: 
sudo systemctl enable torbox-media-center
sudo systemctl start torbox-media-center
Check status: 
sudo systemctl status torbox-media-center

​
Environment variables reference

Required: Optional:
  • MOUNT_METHOD - Either strm or fuse (default: strm)
  • MOUNT_PATH - Directory where media files will be accessible (must exist)
  • MOUNT_REFRESH_TIME - Sync frequency: slowest, very_slow, slow, normal, fast, ultra_fast, or instant (default: normal)
  • ENABLE_METADATA - Enable automatic organization into movies/series folders (default: false)
  • RAW_MODE - Use original file structure without organization (default: false)

​
Updating

To update to the latest version:
1

Stop the application

If running in the foreground, press Ctrl+C. If using systemd:
sudo systemctl stop torbox-media-center
2

Pull latest changes

git pull origin main
Or download the latest ZIP and extract it.
3

Update dependencies

pip3 install -r requirements.txt --upgrade
4

Restart the application

python3 main.py
Or if using systemd:
sudo systemctl start torbox-media-center

​
Troubleshooting

​
Python version issues

Check your Python version: 
python3 --version
If it’s below 3.6, upgrade Python or use pyenv to manage multiple versions.

​
Permission errors

Ensure the mount path exists and is writable: 
mkdir -p ~/torbox
chmod 755 ~/torbox

​
FUSE errors on Linux

Install FUSE development libraries:
Ubuntu/Debian
sudo apt-get install libfuse-dev fuse
Fedora/CentOS
sudo dnf install fuse-devel fuse

​
Missing dependencies

If pip3 install fails, you may need development tools:
Ubuntu/Debian
sudo apt-get install python3-dev build-essential
macOS
xcode-select --install

​
Next steps

After installation:
  1. Your media files will appear at the MOUNT_PATH you configured
  2. Configure your media server to use:
    • Movies: <MOUNT_PATH>/movies
    • TV Shows: <MOUNT_PATH>/series
  3. Check the application logs for any errors
See the Configuration guide for advanced settings and the Troubleshooting guide if you encounter issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us