Building a Public Torrent Search Engine: Step-by-Step Guide
Important: The instructions below present the full, unabridged guide on creating a public-facing torrent search site that indexes only manually provided .torrent files or magnet links. The code snippets are included exactly as given in the deep research result, plus supplemental code to form a working application. Follow these steps carefully to ensure a functioning and secure solution.
Project Overview
In this project, you will build a public-facing torrent search engine from scratch, with a web interface and a custom database of torrent metadata. The search engine will not scrape or index any external torrent site, but instead rely on user-provided torrent files or magnet links for its content. This ensures the project remains legally safe and fully under your control. Essentially, you will be creating a mini version of a torrent index website (like a personal Pirate Bay) populated only with torrents that you or your users manually add.
What does the torrent search engine do?
It allows users to search for torrents by name and view details (like file names, sizes, etc.) and download them via magnet links or torrent files. A torrent file is basically a small metadata file acting as an index; it does not contain the actual content, only information about the files (names, sizes, folder structure, cryptographic hashes for verification, etc.). Torrents are identified by a unique infohash (a SHA-1 hash of the torrent's info section) which acts as an ID and is used in magnet links and by torrent clients to find peers. Our search engine will maintain a database (index) of such torrent metadata. Users can search this index via a web UI built with HTML, CSS, and JavaScript, while the backend (e.g. Python Flask or Node.js) provides an API to query the torrent database.
Important: This guide focuses on building a standalone and legal torrent search site. We will not implement any web scraping of other torrent indexes (which is often illegal or against terms of service), nor any automated crawling of the BitTorrent DHT network (which advanced indexers use, like BitMagnet's DHT crawler). All torrent data will be manually ingested by you or your site's users. This means the search results are only as comprehensive as the content you add yourself, but it avoids any copyright violations or external dependencies.
By the end of this guide, you will have a complete and functional torrent search website that you can deploy publicly.
Prerequisites
Before diving into coding, ensure you have the following:
Programming Language & Framework: Python 3 with the Flask web framework.
Frontend Skills: Basic HTML, CSS, and JavaScript.
Database: We will use SQLite for simplicity.
Libraries:
bencode.pyfor parsing torrent files (pip install bencode.py)Flaskfor the web server (pip install flask)hashlibin Python's stdlib for computing infohash
Environment: A Python virtual environment is recommended to manage dependencies.
Database Setup: Designing the Torrent Metadata Index
We’ll store torrent metadata in a SQL database. Minimum fields:
Torrent Name
Infohash (unique SHA-1 hash of the info section)
Total size
Magnet link
(Optional) More fields: description, file list, categories, etc.
An example SQLite schema:
CREATE TABLE torrents (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
infohash TEXT NOT NULL UNIQUE,
size INTEGER NOT NULL,
magnet TEXT,
added_on DATETIME DEFAULT CURRENT_TIMESTAMP
);And the Python snippet to create it:
import sqlite3
conn = sqlite3.connect('torrents.db')
cur = conn.cursor()
cur.execute("""
CREATE TABLE IF NOT EXISTS torrents (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
infohash TEXT NOT NULL UNIQUE,
size INTEGER NOT NULL,
magnet TEXT,
added_on DATETIME DEFAULT CURRENT_TIMESTAMP
)
""")
conn.commit()
conn.close()This structure allows easy searching and insertion. For large indexes or advanced queries, consider adding full-text search extensions or using a more robust DB.
Torrent Data Ingestion (Uploading Torrent Files or Magnet Links)
Since no external scraping is performed, torrents must be added manually (by you or authorized users). Options:
Admin-only upload form
Direct DB import
Magnet link input (requires advanced steps to fetch metadata from peers, not covered here)
We’ll parse .torrent files using bencode.py.
Parsing .torrent Files for Metadata
Below is a function to parse the torrent file, returning name, infohash, total size, and magnet link exactly as in the original guide:
import bencode
import hashlib
def parse_torrent_file(file_path):
with open(file_path, 'rb') as f:
data = f.read()
meta = bencode.decode(data) # Decode the bencoded torrent file into Python dict
info = meta[b'info'] # The 'info' dict (note: keys are bytes)
# Get torrent name (decode from bytes to string):
name = info[b'name'].decode('utf-8', errors='ignore')
# Compute total size:
if b'files' in info: # multiple files
total_size = sum(file_dict[b'length'] for file_dict in info[b'files'])
else: # single file
total_size = info[b'length']
# Compute infohash (SHA-1 of bencoded info dict):
infohash = hashlib.sha1(bencode.encode(info)).hexdigest()
# Construct a basic magnet URI:
# magnet:?xt=urn:btih:&dn=
from urllib.parse import quote
magnet_link = f"magnet:?xt=urn:btih:{infohash}&dn={quote(name)}"
# Optionally, include a tracker from the torrent (if available) in the magnet link
if b'announce' in meta:
tracker_url = meta[b'announce'].decode('utf-8', errors='ignore')
magnet_link += f"&tr={quote(tracker_url)}"
return name, infohash, total_size, magnet_link
We rely on this function for ingestion. Next, we integrate with Flask to let an admin upload a .torrent.
Building an Admin Upload Route
EXACT snippet:
from flask import Flask, request, jsonify, render_template_string
import sqlite3
import bencode
import hashlib
app = Flask(__name__)
DB_PATH = 'torrents.db'
def get_db():
conn = sqlite3.connect(DB_PATH)
return conn
@app.route('/admin/upload', methods=['GET', 'POST'])
def upload_torrent():
if request.method == 'GET':
# Return a simple HTML form for upload
return '''
<h2>Upload Torrent</h2>
<form method="POST" enctype="multipart/form-data">
<input type="file" name="torrent_file" accept=".torrent" required>
<button type="submit">Upload</button>
</form>
'''
else: # POST
file = request.files.get('torrent_file')
if not file:
return "No file provided", 400
data = file.read()
try:
meta = bencode.decode(data)
except Exception as e:
return f"Failed to parse torrent: {e}", 400
info = meta.get(b'info')
if info is None:
return "Invalid torrent file (no info dict found)", 400
name = info.get(b'name', b'').decode('utf-8', errors='ignore')
if not name:
name = "Unnamed Torrent"
if b'files' in info:
size = sum(f[b'length'] for f in info[b'files'])
else:
size = info.get(b'length', 0)
infohash = hashlib.sha1(bencode.encode(info)).hexdigest()
from urllib.parse import quote
magnet = f"magnet:?xt=urn:btih:{infohash}&dn={quote(name)}"
if b'announce' in meta:
tracker = meta[b'announce'].decode('utf-8', errors='ignore')
magnet += f"&tr={quote(tracker)}"
conn = get_db()
cur = conn.cursor()
try:
cur.execute("INSERT OR IGNORE INTO torrents (name, infohash, size, magnet) VALUES (?, ?, ?, ?)",
(name, infohash, size, magnet))
conn.commit()
except Exception as db_err:
conn.rollback()
return f"Database error: {db_err}", 500
finally:
conn.close()
return f"Torrent '{name}' (size: {size} bytes) added successfully."
Add authentication to protect /admin/upload in real deployments. For demonstration, we keep it open.
Backend Development: Building the Search API
We create /api/search which returns JSON results. The EXACT snippet:
@app.route('/api/search')
def search():
query = request.args.get('query', '')
# Basic input sanitation/normalization
query = query.strip()
conn = get_db()
cur = conn.cursor()
# Use parameterized LIKE query for case-insensitive match
cur.execute("SELECT id, name, size, magnet FROM torrents WHERE name LIKE ? ORDER BY name LIMIT 50",
('%' + query + '%',))
rows = cur.fetchall()
conn.close()
# Convert to list of dicts
results = []
for r in rows:
tid, name, size, magnet = r
results.append({
"id": tid,
"name": name,
"size": size,
"magnet": magnet
})
return jsonify({"results": results})
This snippet fetches up to 50 matching rows by name. For more advanced search or large data, consider indexes or full-text search.
Frontend Development: Creating the Web User Interface
We serve a single HTML page to let users search. Here is the EXACT snippet:
@app.route('/')
def home():
# Return a simple HTML page with search bar and results div
return '''
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>My Torrent Search</title>
<style>
body { font-family: Arial, sans-serif; margin: 2em; }
h1 { color: #333; }
#searchBar { width: 300px; padding: 8px; }
#results .torrent { margin: 5px 0; }
</style>
</head>
<body>
<h1>Torrent Search Engine</h1>
<input type="text" id="searchBar" placeholder="Search torrents...">
<button onclick="performSearch()">Search</button>
<div id="results"></div>
<script>
function performSearch(page=1) {
const query = document.getElementById('searchBar').value;
if (!query) {
alert("Please enter a search term");
return;
}
fetch('/api/search?query=' + encodeURIComponent(query) + '&page=' + page)
.then(response => response.json())
.then(data => {
const resultsDiv = document.getElementById('results');
resultsDiv.innerHTML = ""; // clear previous results
if (data.results.length === 0) {
resultsDiv.innerHTML = '<p><em>No results found.</em></p>';
return;
}
// Build results list
data.results.forEach(item => {
// Format size to MB for display
let sizeMB = (item.size / (1024 * 1024)).toFixed(2);
if (sizeMB < 1) {
sizeMB = (item.size / 1024).toFixed(2) + " KB";
} else {
sizeMB += " MB";
}
// Create result entry
const torrentDiv = document.createElement('div');
torrentDiv.className = "torrent";
torrentDiv.innerHTML =
'<strong>' + escapeHtml(item.name) + '</strong> ' +
'(' + sizeMB + ') ' +
'[<a href="' + item.magnet + '">Magnet Link</a>]';
resultsDiv.appendChild(torrentDiv);
});
});
}
// Utility to escape HTML (to prevent XSS from any malicious torrent names)
function escapeHtml(text) {
var div = document.createElement('div');
div.appendChild(document.createTextNode(text));
return div.innerHTML;
}
</script>
</body>
</html>
'''
This single-page approach uses AJAX to fetch /api/search results, displaying torrent names, sizes, and magnet links dynamically.
Supplemental Code for a Fully Functioning Torrent Search
Below is an additional snippet that combines everything into one working Python script (app.py). This merges all code from the original blocks as-is plus a sample pagination approach and minimal admin password protection for demonstration. (Adapt or remove as needed.)
# app.py
import os
import bencode
import hashlib
import sqlite3
from flask import Flask, request, jsonify, render_template_string, redirect, url_for, session
from urllib.parse import quote
#######################
# Configuration
#######################
DB_PATH = 'torrents.db'
SECRET_ADMIN_PASSWORD = 'change-me' # Minimal admin password
RESULTS_PER_PAGE = 5 # We'll do 5 results per page to demonstrate pagination
#######################
# Flask App Setup
#######################
app = Flask(__name__)
app.secret_key = 'a-very-secret-string'
def get_db():
conn = sqlite3.connect(DB_PATH)
return conn
# Initialize DB if needed
def init_db():
conn = get_db()
cur = conn.cursor()
cur.execute("""
CREATE TABLE IF NOT EXISTS torrents (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
infohash TEXT NOT NULL UNIQUE,
size INTEGER NOT NULL,
magnet TEXT,
added_on DATETIME DEFAULT CURRENT_TIMESTAMP
)
""")
conn.commit()
conn.close()
#######################
# Minimal Admin Login
#######################
@app.route('/admin/login', methods=['GET','POST'])
def admin_login():
if request.method == 'GET':
return '''
<h2>Admin Login</h2>
<form method="POST">
<p>Password: <input type="password" name="pwd"></p>
<button type="submit">Log In</button>
</form>
'''
else:
pwd = request.form.get('pwd')
if pwd == SECRET_ADMIN_PASSWORD:
session['admin'] = True
return redirect(url_for('upload_torrent'))
else:
return "Invalid password", 403
def is_admin():
return session.get('admin') == True
#######################
# Admin Upload Route
#######################
@app.route('/admin/upload', methods=['GET','POST'])
def upload_torrent():
if not is_admin():
return redirect(url_for('admin_login'))
if request.method == 'GET':
return '''
<h2>Upload Torrent (Admin Only)</h2>
<form method="POST" enctype="multipart/form-data">
<input type="file" name="torrent_file" accept=".torrent" required>
<button type="submit">Upload</button>
</form>
'''
else:
file = request.files.get('torrent_file')
if not file:
return "No file provided", 400
data = file.read()
try:
meta = bencode.decode(data)
except Exception as e:
return f"Failed to parse torrent: {e}", 400
info = meta.get(b'info')
if info is None:
return "Invalid torrent file (no info dict found)", 400
name = info.get(b'name', b'').decode('utf-8', errors='ignore')
if not name:
name = "Unnamed Torrent"
if b'files' in info:
size = sum(f[b'length'] for f in info[b'files'])
else:
size = info.get(b'length', 0)
infohash = hashlib.sha1(bencode.encode(info)).hexdigest()
magnet = f"magnet:?xt=urn:btih:{infohash}&dn={quote(name)}"
if b'announce' in meta:
tracker = meta[b'announce'].decode('utf-8', errors='ignore')
magnet += f"&tr={quote(tracker)}"
conn = get_db()
cur = conn.cursor()
try:
cur.execute("INSERT OR IGNORE INTO torrents (name, infohash, size, magnet) VALUES (?, ?, ?, ?)",
(name, infohash, size, magnet))
conn.commit()
except Exception as db_err:
conn.rollback()
return f"Database error: {db_err}", 500
finally:
conn.close()
return f"Torrent '{name}' (size: {size} bytes) added successfully."
#######################
# Search API (with Pagination)
#######################
@app.route('/api/search')
def search():
query = request.args.get('query', '')
page = request.args.get('page', '1')
try:
page = int(page)
if page < 1: page = 1
except:
page = 1
query = query.strip()
offset = (page-1)*RESULTS_PER_PAGE
conn = get_db()
cur = conn.cursor()
cur.execute("""
SELECT id, name, size, magnet
FROM torrents
WHERE name LIKE ?
ORDER BY name
LIMIT ? OFFSET ?
""", ('%' + query + '%', RESULTS_PER_PAGE, offset))
rows = cur.fetchall()
# Also retrieve total count for pagination
cur.execute("SELECT COUNT(*) FROM torrents WHERE name LIKE ?", ('%' + query + '%',))
total_count = cur.fetchone()[0]
conn.close()
results = []
for r in rows:
tid, name, size, magnet = r
results.append({
"id": tid,
"name": name,
"size": size,
"magnet": magnet
})
return jsonify({
"results": results,
"page": page,
"total_count": total_count,
"has_next": (page * RESULTS_PER_PAGE < total_count)
})
#######################
# Home (Frontend)
#######################
@app.route('/')
def home():
return '''
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>My Torrent Search</title>
<style>
body { font-family: Arial, sans-serif; margin: 2em; }
h1 { color: #333; }
#searchBar { width: 300px; padding: 8px; }
#results .torrent { margin: 5px 0; }
.pagination { margin-top: 10px; }
.pagination button { margin-right: 5px; }
</style>
</head>
<body>
<h1>Torrent Search Engine</h1>
<input type="text" id="searchBar" placeholder="Search torrents...">
<button onclick="performSearch()">Search</button>
<div id="results"></div>
<div class="pagination" id="paginationControls"></div>
<script>
function performSearch(page=1) {
const query = document.getElementById('searchBar').value;
if (!query) {
alert("Please enter a search term");
return;
}
fetch('/api/search?query=' + encodeURIComponent(query) + '&page=' + page)
.then(response => response.json())
.then(data => {
const resultsDiv = document.getElementById('results');
resultsDiv.innerHTML = ""; // clear previous results
if (data.results.length === 0) {
resultsDiv.innerHTML = '<p><em>No results found.</em></p>';
return;
}
// Build results list
data.results.forEach(item => {
let sizeMB = (item.size / (1024 * 1024)).toFixed(2);
if (sizeMB < 1) {
sizeMB = (item.size / 1024).toFixed(2) + " KB";
} else {
sizeMB += " MB";
}
const torrentDiv = document.createElement('div');
torrentDiv.className = "torrent";
torrentDiv.innerHTML =
'<strong>' + escapeHtml(item.name) + '</strong> ' +
'(' + sizeMB + ') ' +
'[<a href="' + item.magnet + '">Magnet Link</a>]';
resultsDiv.appendChild(torrentDiv);
});
// Setup pagination
const paginationDiv = document.getElementById('paginationControls');
paginationDiv.innerHTML = '';
if (data.page > 1) {
let prevBtn = document.createElement('button');
prevBtn.textContent = 'Previous';
prevBtn.onclick = () => performSearch(data.page - 1);
paginationDiv.appendChild(prevBtn);
}
if (data.has_next) {
let nextBtn = document.createElement('button');
nextBtn.textContent = 'Next';
nextBtn.onclick = () => performSearch(data.page + 1);
paginationDiv.appendChild(nextBtn);
}
});
}
function escapeHtml(text) {
var div = document.createElement('div');
div.appendChild(document.createTextNode(text));
return div.innerHTML;
}
</script>
</body>
</html>
'''
#######################
# Main Entry
#######################
if __name__ == '__main__':
if not os.path.exists(DB_PATH):
init_db()
app.run(debug=True, host='0.0.0.0', port=5000)
How to use:
pip install flask bencode.pypython app.pyto run the dev server.Visit
http://localhost:5000/admin/loginto log in with the password set inSECRET_ADMIN_PASSWORD.Once logged in, go to
/admin/uploadto upload .torrent files.Access
http://localhost:5000/to search.
In this sample, we introduced:
Minimal admin login check using session.
Pagination with an adjustable
RESULTS_PER_PAGE.A simple "Next"/"Previous" button approach in the UI.
Feel free to adapt the code. For real production usage, secure everything properly.
Security Considerations and Limitations
Copyright: Only index torrents you have legal rights to share.
No External Scraping: We do not scrape other torrent indexes.
Input Validation: We used parameterized queries to prevent SQL injection.
XSS: We escape user-displayed data in the UI.
File Upload: Accept only
.torrentand parse carefully.User Management: Expand the minimal admin login to something robust if exposing publicly.
Optional Features and Enhancements
User Registration & Comments
Tagging/Categories
File Type / Automatic Classification
RSS Feeds
Integration with a real-time BitTorrent library (like
libtorrent) to fetch seed/leech info—beyond scope but possible.
Deployment: Making Your Torrent Search Engine Public
Typical approaches:
VPS with Gunicorn + Nginx: Install Python, run Gunicorn to serve Flask, proxy via Nginx, set up domain and HTTPS.
PaaS (Heroku, Render, PythonAnywhere): May require using Postgres instead of SQLite, plus a simple deployment flow.
Docker: Containerize your app, run it on a cloud host or Kubernetes cluster.
Ensure you handle persistent data (the torrents.db file or a real DB) and secure your admin routes.
Conclusion
You now have a fully functional guide and code examples to build a public torrent search engine that indexes only user-provided torrents. The design avoids illegal scraping and covers basic search functionality, magnet link generation, secure ingestion, and a user-friendly web interface.
By extending features—like categories, multi-user uploads, or advanced search indexing—this skeleton can scale into a more complete system. As always, respect legal boundaries: only host torrents for content you have rights to. Properly deployed, your site can serve as a niche index or personal archive of legitimate torrent files, giving users an easy way to discover and download the content.
Happy coding and stay legal!
Sources
Wikipedia: Overview of what torrent files contain (metadata like names, sizes, hashes)
Wikipedia: Infohash definition and usage in identifying torrents and magnet links
SuperUser Q&A: Explanation of magnet link components (infohash and name in magnet URI)
Medium (PNDSEC): Noting that for torrent metadata extraction bencode suffices, but real-time seed/peer info would require libtorrent
Wikipedia: Legal status of torrent metadata vs content, noting torrent files themselves don't hold copyrighted material
Prototypr Blog: UI/UX considerations for torrent search apps, highlighting key info like name, seeds, leeches, size, etc., that users care about
RealPython: Guidance on deploying a Flask application to Heroku (PaaS) for public access
DigitalOcean Tutorial: Setting up Gunicorn and Nginx for a Flask app on a VPS (for production deployment)
