pySmartDL

1.3.4 · maintenance · verified Thu Apr 16

pySmartDL is a Smart Download Manager for Python, providing features such as built-in download acceleration, mirror support, pause/unpause, speed limiting, and hash checking. It operates in a non-blocking manner and shows a progress bar, download speed, and ETA. The library version 1.3.4 was last updated on PyPI in September 2020, and the original project is not actively maintained, though a community fork exists.

Common errors

```
ImportError: No module named pySmartDL
```
cause The `pySmartDL` library is not installed, or the Python environment where the script is run does not have access to the installed package.

fix Ensure the library is installed in the correct environment: `pip install pySmartDL`
```
pySmartDL.HashFailedException: HashFailedException(filename, got calculated_hash, expected needed_hash)
```
cause The downloaded file's hash does not match the expected hash provided by `add_hash_verification()`, indicating data corruption or a tampered file.

fix Verify the source of the file and the correctness of the expected hash. If mirrors are provided, `pySmartDL` will attempt other mirrors. If the issue persists, the downloaded content is genuinely different from its expected hash.
```
HTTP Error 403: Forbidden (or similar HTTP error codes like 404, 500)
```
cause The server denied access to the URL, the URL does not exist, or there's a server-side issue. This can often be due to missing or incorrect HTTP headers (e.g., User-Agent, Referer) or rate limiting.

fix Inspect `obj.get_errors()` for details. For 403 errors, try adding a `User-Agent` header via `request_args`: `SmartDL(url, dest, request_args={'headers': {'User-Agent': 'Mozilla/5.0 (compatible; pySmartDL/1.3.4)'}})`. For 404, check the URL.

Warnings

deprecated The original `pySmartDL` project (iTaybb/pySmartDL) is no longer actively maintained. While it may still function, it does not receive new features, bug fixes, or compatibility updates for newer Python versions or web standards. A community-maintained fork, `pysmartdl2`, exists.
Fix: Consider migrating to the `pysmartdl2` fork (`pip install pysmartdl2`) for ongoing support and updates, or be aware that the original library may have unpatched issues.
gotcha HTTP 403 Forbidden errors can occur when downloading from certain URLs. This is often due to websites blocking requests that don't mimic a standard browser, for example, by checking the User-Agent header or requiring specific cookies/referrers.
Fix: Try passing custom headers to `SmartDL` using the `request_args` parameter, including a `User-Agent`. Example: `obj = SmartDL(url, dest, request_args={'headers': {'User-Agent': 'Mozilla/5.0'}})`
gotcha By default, `SmartDL.wait()` does not raise exceptions, instead storing them internally, which can make debugging difficult. The `SmartDL.start()` method, when called without arguments, internally calls `wait()`.
Fix: To catch exceptions like `HashFailedException` directly, call `obj.start(blocking=True)` or `obj.wait(raise_exceptions=True)` within a `try...except` block. Otherwise, inspect `obj.get_errors()` after the download finishes.
gotcha The `verify` parameter in `SmartDL` controls SSL certificate validation (default is `True`). Disabling it can resolve SSL-related connection issues but exposes the application to security vulnerabilities by bypassing certificate checks.
Fix: Only set `verify=False` if you understand and accept the security implications, typically in trusted environments or for specific, non-sensitive internal resources. `obj = SmartDL(url, dest, verify=False)`

Install

pip install pySmartDL Install latest stable version

Imports

SmartDL
```
from pySmartDL import SmartDL
```
HashFailedException
```
from pySmartDL import SmartDL, HashFailedException
```
Import HashFailedException for specific error handling.

Quickstart

This quickstart downloads a file to a specified destination. The `SmartDL` object's `start()` method is blocking by default. Error handling is included to report any download failures.

import os
from pySmartDL import SmartDL

# A URL to download (using a dummy placeholder for actual use)
url = "https://example.com/some_file.zip" 
# Ensure the destination directory exists
dest = os.path.join(os.getcwd(), "downloads")
os.makedirs(dest, exist_ok=True)

obj = SmartDL(url, dest)
obj.start() # Blocks until download is complete

if obj.isSuccessful():
    print(f"Download finished: {obj.get_dest()}")
else:
    print("Download failed. Errors:")
    for e in obj.get_errors():
        print(str(e))

view raw JSON →