{"id":9701,"library":"download","title":"Download File Utility","description":"The `download` library provides a simple, high-level function for downloading files from the internet, including optional extraction of zip archives. It's built on `urllib.request` and offers progress bars via `tqdm`. The current version is 0.3.5, and it maintains a relatively stable API with infrequent releases.","status":"active","version":"0.3.5","language":"en","source_language":"en","source_url":"https://github.com/choldgraf/download","tags":["download","file","http","utility","archive","progress-bar"],"install":[{"cmd":"pip install download","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides progress bars for downloads, enhancing user experience.","package":"tqdm","optional":false}],"imports":[{"note":"The primary functionality is exposed as a function named 'download' within the 'download' module. You can also import the module and call `download.download(...)`.","wrong":"import download.download","symbol":"download","correct":"from download import download"}],"quickstart":{"code":"import download\nimport os\n\n# Define the output directory\noutput_dir = './my_downloads'\nos.makedirs(output_dir, exist_ok=True)\n\n# Example of a small, public file to download (e.g., a license file from GitHub)\n# Using a raw GitHub URL to ensure direct file access for demonstration.\nfile_url = 'https://raw.githubusercontent.com/choldgraf/download/main/LICENSE'\n\ntry:\n    print(f\"Attempting to download {file_url} to {output_dir}\")\n    # Download the file with progress and replace if it exists\n    download.download(\n        url=file_url,\n        path=output_dir,\n        replace=True, # Overwrite if file exists\n        verbose=True  # Show progress bar\n    )\n    print(f\"Successfully downloaded {file_url} to {output_dir}\")\n\n    # Example of downloading and extracting a zip file (if you have a test zip URL)\n    # For this example, we'll just demonstrate the call signature, as a suitable public test zip is not always guaranteed.\n    # zip_file_url = 'https://github.com/choldgraf/download/archive/refs/heads/main.zip'\n    # print(f\"\\nAttempting to download and extract a zip from {zip_file_url}\")\n    # download.download(\n    #     url=zip_file_url,\n    #     path=output_dir,\n    #     extract=True,  # Extract the contents of the zip file\n    #     replace=True,\n    #     verbose=True\n    # )\n    # print(f\"Successfully downloaded and extracted {zip_file_url} to {output_dir}\")\n\nexcept Exception as e:\n    print(f\"An error occurred during download: {e}\")\n\n# Optional: Clean up the created directory\n# import shutil\n# if os.path.exists(output_dir):\n#     print(f\"\\nCleaning up {output_dir}\")\n#     shutil.rmtree(output_dir)","lang":"python","description":"The quickstart demonstrates the core functionality of downloading a file from a URL to a specified directory. It uses `download.download()` with `verbose=True` for progress and `replace=True` to ensure idempotency. The library also supports `extract=True` for automatic unzipping of archives."},"warnings":[{"fix":"The recommended fix is to ensure the target server has a valid SSL certificate. If this is not possible and you understand the security implications, you might need to globally or contextually bypass SSL verification using Python's `ssl` module, which is outside the direct scope of the `download` library's API.","message":"The `download` library, leveraging `urllib.request`, performs strict SSL/TLS certificate verification. Downloads from HTTPS URLs with invalid, expired, or self-signed certificates will typically fail with an `URLError` containing `CERTIFICATE_VERIFY_FAILED`. The library does not expose a direct `verify=False` parameter.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To ensure that existing files are always updated, explicitly set the `replace=True` argument when calling `download.download()`.","message":"By default, `download.download()` will *not* overwrite an existing file at the target path. If a file with the same name already exists, the download operation will be skipped silently, potentially leading to stale local files.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the user running the Python script has write permissions to the specified output directory. Pre-creating the directory with `os.makedirs(path, exist_ok=True)` can help isolate permission issues. Handle `PermissionError` or `IsADirectoryError` if encountered.","message":"While `download` automatically creates the output directory if it doesn't exist, issues can arise from insufficient write permissions for the specified `path` or if a file (rather than a directory) already exists at the intended output `path`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install download`.","cause":"The 'download' library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'download'"},{"fix":"Ensure you are calling the function correctly: `from download import download` then `download(...)` OR `import download` then `download.download(...)`. Verify no local files named `download.py` are interfering.","cause":"This error typically occurs if you're trying to call `download.download()` but have a local file named `download.py` that shadows the installed library, or if `from download import download` was intended but used incorrectly. It can also happen if you're trying to access a non-existent attribute.","error":"AttributeError: module 'download' has no attribute 'download'"},{"fix":"Confirm the server's certificate is valid. If you control the server, update the certificate. If this is a known issue for an internal server, you might need to explore options to manage SSL contexts, but disabling verification is a security risk.","cause":"The target HTTPS server uses an invalid, expired, or self-signed SSL/TLS certificate, and Python's `urllib.request` (used by `download`) is enforcing strict certificate validation.","error":"URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:XXXX)>"},{"fix":"Run your Python script with a user account that has write access to the target directory. Alternatively, specify an output directory where write permissions are granted (e.g., a temporary directory or a user-specific folder).","cause":"The Python process lacks the necessary write permissions to save the file or create the directory at the specified `path`.","error":"PermissionError: [Errno 13] Permission denied: '/path/to/protected_dir/file.zip'"}]}