[v1.0] feat: add migration guide for v1.0 (#3360)

google-labs-jules[bot] · Wauplin · hanouticelina · web-flow · commit 470a7eec6477 · 2025-10-01T13:43:19.000+02:00
* [1.0] Httpx migration (#3328) * first httpx integration * more migration * some fixes * download workflow should work * Fix repocard and error utils tests * fix hf-file-system * gix http utils tests * more fixes * fix some inference tests * fix test_file_download tests * async inference client * async code should be good * Define RemoteEntryFileNotFound explicitly (+some fixes) * fix async code quality * torch ok * fix hf_file_system * fix errors tests * mock * fix test_cli mock * fix commit scheduler * add fileno test * no more requests anywhere * fix test_file_download * tmp requests * Update src/huggingface_hub/utils/_http.py Co-authored-by: célina <hanouticelina@gmail.com> * Update src/huggingface_hub/utils/_http.py Co-authored-by: célina <hanouticelina@gmail.com> * Update src/huggingface_hub/hf_file_system.py Co-authored-by: célina <hanouticelina@gmail.com> * not async * fix tests --------- Co-authored-by: célina <hanouticelina@gmail.com> * Bump minimal version to Python3.9 (#3343) * Bump minimal version to Python3.9 * use built-in generics * code quality * new batch * yet another btach * fix dataclass_with_extra * fix * keep Type for strict dataclasses * fix test * Remove `HfFolder` and `InferenceAPI` classes (#3344) * Remove HfFolder * Remove InferenceAPI * more recent gradio * bump pytest * fix python 3.9? * install gradio only on python 3.10+ * fix tests * fix tests * fix * [v1.0] Remove more deprecated stuff (#3345) * remove constants.-hf_cache_home * remove smoothly_deprecate_use_auth_token * remove get_token_permission * remove update_repo_visibility * remove is_write_action arg * remove write_permission arg from login methods * new parameter skip_if_logged_in in login methods * Remove resume_download / force_filename parameters * Remove deprecated local_dir_use_symlinks parameter * Remove deprecated language, library, task, tags from list_models * Return commit URL in upload_file/upload_folder (previously url to file/folder on the Hub) * fix upload_file/upload_folder tests * smoothly_deprecate_legacy_arguments everywhere * code quality * fix tests * fix xet tests * [v1.0] Remove `Repository` class (#3346) * Remove Repository class + adapt docs * remove fr git_vs_http * bump to 1.0.0.dev0 * Remove _deprecate_positional_args on login methods (#3349) * [v1.0] Remove imports kept only for backward compatibility (#3350) * Remove imports kept only for backward compatibility * fix tests * [v1.0] Remove keras2 utilities (#3352) * Remove keras2 utilities * remove keras from init * [v1.0] Remove anything tensorflow-related + deps (#3354) * Remove anything tensorflow-related + deps * init * fix tests * fix conflicts in tests * HTTP configuration docs * http configuration docs * refactored git_vs_http * feat: add migration guide for v1.0 This commit adds a comprehensive migration guide for the v1.0 release of the `huggingface_hub` library. The guide is located at `docs/source/en/concepts/migration.md` and provides a detailed list of main changes and breaking changes, along with instructions on how to adapt to them. The migration guide covers the following topics: - HTTPX migration - Python 3.9+ requirement - Removal of deprecated features - Removal of the `Repository`, `HfFolder`, and `InferenceApi` classes - Removal of TensorFlow and Keras 2 integrations This guide is intended to help users migrate their existing code to the new version of the library smoothly. Fixes #3358 [Auto-generated by https://jules.google.com/] * rewrite migration guide * fix import * fix docs? * add why httpx section * Update docs/source/en/concepts/migration.md --------- Co-authored-by: Lucain <lucain@huggingface.co> Co-authored-by: célina <hanouticelina@gmail.com> Co-authored-by: Lucain Pouget <lucainp@gmail.com> Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
diff --git a/docs/source/en/_toctree.yml b/docs/source/en/_toctree.yml
@@ -46,6 +46,8 @@
   sections:
     - local: concepts/git_vs_http
       title: Git vs HTTP paradigm
+    - local: concepts/migration
+      title: Migrating to huggingface_hub v1.0
 - title: 'Reference'
   sections:
     - local: package_reference/overview
diff --git a/docs/source/en/concepts/migration.md b/docs/source/en/concepts/migration.md
@@ -0,0 +1,95 @@
+# Migrating to huggingface_hub v1.0
+
+The v1.0 release is a major milestone for the `huggingface_hub` library. It marks our commitment to API stability and the maturity of the library. We have made several improvements and breaking changes to make the library more robust and easier to use.
+
+This guide is intended to help you migrate your existing code to the new version. If you have any questions or feedback, please let us know by [opening an issue on GitHub](https://github.com/huggingface/huggingface_hub/issues).
+
+## Python 3.9+
+
+`huggingface_hub` now requires Python 3.9 or higher. Python 3.8 is no longer supported.
+
+## HTTPX migration
+
+The `huggingface_hub` library now uses [`httpx`](https://www.python-httpx.org/) instead of `requests` for HTTP requests. This change was made to improve performance and to support both synchronous and asynchronous requests the same way. We therefore dropped both `requests` and `aiohttp` dependencies.
+
+### Breaking changes
+
+This is a major change that affects the entire library. While we have tried to make this change as transparent as possible, you may need to update your code in some cases. Here is a list of breaking changes introduced in the process:
+
+- **Proxy configuration**: "per method" proxies are no longer supported. Proxies must be configured globally using the `HTTP_PROXY` and `HTTPS_PROXY` environment variables.
+- **Custom HTTP backend**: The `configure_http_backend` function has been removed. You should now use [`set_client_factory`] and [`set_async_client_factory`] to configure the HTTP clients.
+- **Error handling**: HTTP errors are not inherited from `requests.HTTPError` anymore, but from `httpx.HTTPError`. We recommend catching `huggingface_hub.HfHubHttpError` which is a subclass of `requests.HTTPError` in v0.x and of `httpx.HTTPError` in v1.x. Catching from the `huggingface_hub` error ensures your code is compatible with both the old and new versions of the library.
+- **SSLError**: `httpx` does not have the concept of `SSLError`. It is now a generic `httpx.ConnectError`.
+- **`LocalEntryNotFoundError`**: This error no longer inherits from `HTTPError`. We now define a `EntryNotFoundError` (new) that is inherited by both [`LocalEntryNotFoundError`] (if file not found in local cache) and [`RemoteEntryNotFoundError`] (if file not found in repo on the Hub). Only the remote error inherits from `HTTPError`.
+- **`InferenceClient`**: The `InferenceClient` can now be used as a context manager. This is especially useful when streaming tokens from a language model to ensure that the connection is closed properly.
+- **`AsyncInferenceClient`**: The `trust_env` parameter has been removed from the `AsyncInferenceClient`'s constructor. Environment variables are trusted by default by `httpx`. If you explicitly don't want to trust the environment, you must configure it with [`set_client_factory`].
+
+For more details, you can check [PR #3328](https://github.com/huggingface/huggingface_hub/pull/3328) that introduced `httpx`.
+
+### Why `httpx`?
+
+
+The migration from `requests` to `httpx` brings several key improvements that enhance the library's performance, reliability, and maintainability:
+
+**Thread Safety and Connection Reuse**: `httpx` is thread-safe by design, allowing us to safely reuse the same client across multiple threads. This connection reuse reduces the overhead of establishing new connections for each HTTP request, improving performance especially when making frequent requests to the Hub.
+
+**HTTP/2 Support**: `httpx` provides native HTTP/2 support, which offers better efficiency when making multiple requests to the same server (exactly our use case). This translates to lower latency and reduced resource consumption compared to HTTP/1.1.
+
+**Unified Sync/Async API**: Unlike our previous setup with separate `requests` (sync) and `aiohttp` (async) dependencies, `httpx` provides both synchronous and asynchronous clients with identical behavior. This ensures that `InferenceClient` and `AsyncInferenceClient` have consistent functionality and eliminates subtle behavioral differences that previously existed between the two implementations.
+
+**Improved SSL Error Handling**: `httpx` handles SSL errors more gracefully, making debugging connection issues easier and more reliable.
+
+**Future-Proof Architecture**: `httpx` is actively maintained and designed for modern Python applications. In contrast, `requests` is in maintenance mode and won't receive major updates like thread-safety improvements or HTTP/2 support.
+
+**Better Environment Variable Handling**: `httpx` provides more consistent handling of environment variables across both sync and async contexts, eliminating previous inconsistencies where `requests` would read local environment variables by default while `aiohttp` would not.
+
+The transition to `httpx` positions `huggingface_hub` with a modern, efficient, and maintainable HTTP backend. While most users should experience seamless operation, the underlying improvements provide better performance and reliability for all Hub interactions.
+
+## `Repository` class
+
+The `Repository` class has been removed in v1.0. It was a thin wrapper around the `git` CLI for managing repositories. You can still use `git` directly in the terminal, but the recommended approach is to use the HTTP-based API in the `huggingface_hub` library for a smoother experience, especially when dealing with large files.
+
+Here is a mapping from the legacy `Repository` class to the new `HfApi` one:
+
+| `Repository` method                        | `HfApi` method                                        |
+| ------------------------------------------ | ----------------------------------------------------- |
+| `repo.clone_from`                          | `snapshot_download`                                   |
+| `repo.git_add` + `git_commit` + `git_push` | [`upload_file`], [`upload_folder`], [`create_commit`] |
+| `repo.git_tag`                             | `create_tag`                                          |
+| `repo.git_branch`                          | `create_branch`                                       |
+
+## `HfFolder` class
+
+`HfFolder` was used to manage the user access token. Use [`login`] to save a new token, [`logout`] to delete it and [`whoami`] to check the user associated to the current token. Finally, use [`get_token`] to retrieve user's token in a script.
+
+
+## `InferenceApi` class
+
+`InferenceApi` was a class to interact with the Inference API. It is now recommended to use the [`InferenceClient`] class instead.
+
+## Other deprecated features
+
+Some methods and parameters have been removed in v1.0. The ones listed below have already been deprecated with a warning message in v0.x.
+
+- `constants.hf_cache_home` has been removed. Please use `HF_HOME` instead.
+- `use_auth_token` parameters have been removed from all methods. Please use `token` instead.
+- `get_token_permission` method has been removed.
+- `update_repo_visibility` method has been removed. Please use `update_repo_settings` instead.
+- `is_write_action` parameter has been removed from `build_hf_headers` as well as `write_permission` from `login`. The concept of "write permission" has been removed and is no longer relevant now that fine-grained tokens are the recommended approach.
+- `new_session` parameter in `login` has been renamed to `skip_if_logged_in` for better clarity.
+- `resume_download`, `force_filename`, and `local_dir_use_symlinks` parameters have been removed from `hf_hub_download` and `snapshot_download`.
+- `library`, `language`, `tags`, and `task` parameters have been removed from `list_models`.
+
+## TensorFlow and Keras 2.x support
+
+All TensorFlow-related code and dependencies have been removed in v1.0. This includes the following breaking changes:
+
+- `huggingface_hub[tensorflow]` is no longer a supported extra dependency
+- The `split_tf_state_dict_into_shards` and `get_tf_storage_size` utility functions have been removed.
+- The `tensorflow`, `fastai`, and `fastcore` versions are no longer included in the built-in headers.
+
+The Keras 2.x integration has also been removed. This includes the `KerasModelHubMixin` class and the `save_pretrained_keras`, `from_pretrained_keras`, and `push_to_hub_keras` utilities. Keras 2.x is a legacy and unmaintained library. The recommended approach is to use Keras 3.x which is tightly integrated with the Hub (i.e. it contains built-in method to load/push to Hub). If you still want to work with Keras 2.x, you should downgrade `huggingface_hub` to v0.x version.
+
+## `upload_file` and `upload_folder` return values
+
+The [`upload_file`] and [`upload_folder`] functions now return the URL of the commit created on the Hub. Previously, they returned the URL of the file or folder. This is to align with the return value of [`create_commit`], [`delete_file`] and [`delete_folder`].
