Tarif de lancement (jusqu’au 25 déc.), garanti tant que vous restez abonné : Go à $10/mois (au lieu de $20), Plus avec Opus 5.5 à seulement $30/mois (au lieu de $50)S’abonner →

Browser-Use 1.0 : guide d’installation et de migration

Si vous avez construit votre projet avec browser-use 0.x, la version 1.0 change à la fois l’architecture et les paramètres par défaut. Les 24 actions du navigateur sont remplacées par un REPL Python persistant, tandis que Browser() ouvre désormais un navigateur cloud. Ce guide détaille l’installation de la version 1.0.7, le premier lancement et la migration depuis 0.x, à partir des notes de version de 1.0.7, du fichier MIGRATING.md et de l’article technique du 20 novembre.

Lancer la version 1.0 en 5 minutes

Commencez par figer la version. La version 1.0.0 est sortie le 10 novembre 2026 et la 1.0.7 était le tag stable au 20 novembre, tandis que la 1.0.8rc1 était encore en préversion (versions). Le README précise explicitement de ne jamais utiliser >=, car les API peuvent changer entre deux versions mineures.

bash
uv add 'browser-use==1.0.7'
# or
pip install 'browser-use==1.0.7'

Les prérequis sont simples : Python 3.11 ou une version ultérieure, mais inférieure à 4.0 (README, PyPI). Toutes les dépendances sont verrouillées avec == : c’est idéal pour la reproductibilité, mais cela peut entrer en conflit avec les versions de pydantic, mcp ou google-genai utilisées par votre application.

Authentifiez-vous une seule fois. Créez une clé sur cloud.browser-use.com, puis exportez-la ou lancez l’assistant de connexion :

bash
export BROWSER_USE_API_KEY=bu_...
# or
browser-use login

La commande de connexion enregistre les identifiants dans ~/.config/browser-harness/auth.json. Ils sont ensuite partagés par la CLI, le serveur MCP et browser-harness (MIGRATING.md). Dans un conteneur, utilisez BROWSER_USE_AUTO_LOGIN=true. Sur une machine distante en SSH ou sans interface graphique, la release candidate 1.0.8 affiche un lien et un code de validation à approuver depuis un autre appareil (notes de 1.0.8rc1).

Le premier lancement tient en trois lignes :

python
from browser_use import Agent

result = Agent(
    "Find the number of stars of the browser-use repo"
).run_sync()

print(result.final_result())

Par défaut, cette exécution est facturée : elle utilise un navigateur Browser Use Cloud ainsi que le modèle de passerelle configuré par défaut (README, parcours 1 et 3, paramètres par défaut de MIGRATING.md). Pour tester sans aucune dépense cloud, ajoutez dès maintenant Browser('chromium') et votre propre llm.

Ce qui remplace les 24 actions

Avec browser-use 0.x, le modèle choisissait une action dans un menu à chaque étape, à partir d’une représentation du DOM. La version 1.0 supprime ce menu. Le modèle dispose désormais d’un seul outil principal python : un REPL persistant qui préimporte les utilitaires de browser-harness ainsi que le cdp() brut, le tout construit sur Pydantic AI (article technique) :

python
async def python(ctx: RunContext[Session], code: str) -> list[Any]:
    """Run Python in the persistent REPL
    (browser-harness helpers and raw cdp() pre-imported)."""

Cette refonte a supprimé 136 905 lignes et en a ajouté 29 601 sur 554 fichiers. Le nombre de fichiers Python est passé de 178 à 43 (article technique).

L’exemple le plus parlant concerne la récupération après le blocage d’une page : l’agent a appelé Page.stopLoading, bloqué le script qui ne répondait plus, rechargé la page, trouvé son endpoint JSONP privé, puis récupéré 730 dates par lots en ne relançant que les lots en échec. Résultat : 4 720 lignes, sans outil dédié à aucune de ces opérations (article technique).

La règle conservée par l’équipe est simple : ne créer un helper que si le modèle ne peut pas le réécrire après l’avoir lu une fois. CAPTCHA fait exception. Dans un petit test de staging, les instructions en langage naturel ont obtenu 0/3 sur hCaptcha, alors que l’outil dédié solve_captcha a réussi 6 fois sur 6, car il active un mécanisme auquel la page n’a pas accès (article technique).

Pour les performances et le coût, mieux vaut lire les précautions méthodologiques avant de retenir les gros chiffres. L’article du 20 novembre indique que les trois mêmes modèles ont obtenu de 14 à 33 points supplémentaires, pour un coût 2,7 à 5,2 fois inférieur avec la 1.0 par rapport à la 0.x. Le test portait sur 200 tâches lancées le 8 novembre, dont 180 évaluées. L’article précise aussi qu’il ne s’agissait que d’un lancement par modèle, avec des paramètres par défaut différents : la nouvelle architecture ne peut donc pas être tenue seule responsable des résultats (article technique).

Les comparaisons les plus propres sont plus ciblées. La version 1.0.4 a obtenu 76,1 contre 76,0 pour la 1.0.3, tandis que le coût du modèle est passé de 0,434 $ à 0,208 $ par tâche après la suppression des captures d’écran redondantes, qui a préservé la mise en cache des prompts (notes de la 1.0.4). Dans BU Bench v2, la 1.0 en mode ultrafast atteint 62,5 points, pour 0,070 $ et 650 secondes, contre 56,3 points, 0,082 $ et 743 secondes pour Browser Use Pi. Les auteurs estiment toutefois que l’écart perd sa significativité une fois les erreurs des fournisseurs exclues. Prévoyez donc un outil moins cher et plus rapide, pas automatiquement plus intelligent.

Les paramètres par défaut qui changent discrètement la facture et le navigateur

Ce tableau compile les informations de MIGRATING.md et des notes de version 1.0.6. Il correspond à la 1.0.7 et tient compte du changement de modèle par défaut intervenu au milieu de la série 1.0, souvent absent des anciens guides.

Paramètre0.x1.0.7
llm=NoneModèle obligatoirebu-4.0 via la passerelle Browser Use
Prix de bu-4.0n/a1,80 $ / 1 M en entrée, 9,00 $ / 1 M en sortie
Prix de bu-fastn/a0,12 $ / 1 M en entrée, 0,60 $ / 1 M en sortie
Browser()Chromium localNavigateur Browser Use Cloud
Navigateur localPar défautBrowser('chromium') explicitement
Clé APIUne par fournisseurUne seule BROWSER_USE_API_KEY
max_steps500100 (une étape réservée à la livraison)
Délai d’expiration de l’agentNon spécifié1 700 secondes, hors démarrage et arrêt
ÉvaluationÀ activerjudge=True par défaut
Raisonnement / moden/areasoning='medium', mode='ultrafast' avec bu-fast / bu-ultrafast
Gateway model price per 1M tokens, bu-4.0 versus bu-fast

Trois pièges méritent d’être soulignés. D’abord, le modèle par défaut a changé en cours de série 1.0 : jusqu’à la 1.0.5, il s’agissait de bu-fast, mais la 1.0.6 est passée à bu-4.0, dont le prix au token est 15 fois supérieur. L’exemple du projet chiffre le même test court à 0,022 $ avec bu-4.0, contre 0,0014 $ avec bu-fast. Passez explicitement llm='bu-fast' pour retrouver l’ancien profil tarifaire. Ensuite, un simple Browser() provisionne désormais un navigateur cloud facturé 0,06 $ par heure de navigateur, auxquels s’ajoutent le coût du modèle et celui des recherches (README). Les navigateurs cloud ne peuvent par ailleurs pas accéder à localhost ni aux adresses IP privées (MIGRATING.md). Enfin, une étape correspond à une requête du modèle et à une cellule Python : la limite abaissée à 100 étapes sert donc aussi de plafond de dépenses. Avec max_steps < 1 ou timeout <= 0, l’exécution échoue avant même le démarrage du navigateur (MIGRATING.md).

L’évaluateur constitue l’autre coût caché. Après toute exécution comportant au moins une étape, votre propre modèle effectue une requête supplémentaire, peu coûteuse, sur un maximum de 120 000 caractères de trace et, si la vision est activée, sur les quatre dernières images distinctes, dont la page finale. Ces données sont envoyées sans masquage (MIGRATING.md). Le résultat est disponible dans result.judgement, avec success, failure_reason, gotchas et les indicateurs bot/CAPTCHA. Son coût est inclus dans result.cost_usd. Désactivez-le avec judge=False ou fournissez judge_context avec la réponse attendue. Définissez use_vision=False si les captures d’écran ne doivent jamais sortir de votre périmètre.

Restez en local quand c’est indispensable

Choisissez le navigateur en fonction du réseau auquel il doit accéder, pas par simple habitude. L’identifiant de modèle ci-dessous reprend l’exemple de fournisseur utilisé par le README pour un navigateur local (README) :

python
from browser_use import Agent, Browser, ChatOpenAI

agent = Agent(
    "Summarize the dashboard at http://localhost:3000",
    llm=ChatOpenAI("gpt-6-luna"),
    browser=Browser("chromium"),
)
print(agent.run_sync().final_result())

Utilisez Browser('chromium') pour localhost, les réseaux privés, les fenêtres d’affichage personnalisées ou les situations où les appels cloud de mesure de l’appareil ne refléteraient pas la véritable fenêtre de la page. Utilisez Browser('chrome') pour piloter votre Chrome déjà ouvert avec ses connexions existantes. Browser('chrome', profile='Work') lance une copie temporaire avec les sessions, mais la synchronisation ne réécrit rien ; sous Windows, quittez d’abord le Chrome original, car il verrouille les cookies (MIGRATING.md). Le cloud reste le choix adapté si vous avez besoin d’un mode furtif géré, de proxys, de la gestion des CAPTCHA ou d’une configuration locale minimale (README). Pensez simplement à comptabiliser séparément les heures de navigateur et les tokens.

Les modèles personnalisés restent compatibles, mais le chemin utilisé est important (MIGRATING.md) :

  • Alias de passerelle : bu-4.0, bu-4.0-mini, bu-4.0-pro, bu-fast, bu-ultrafast, bu-smart
  • Fournisseurs : ChatOpenAI, ChatAnthropic, ChatGoogle ou des chaînes Pydantic AI comme groq:llama-3.3-70b-versatile
  • Azure via llm='azure:<deployment>' avec AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY et OPENAI_API_VERSION

Les objets de chat LangChain passés sous la forme Agent(llm=...) déclenchent désormais une TypeError. Les anciens noms de passerelle, comme bu-2-0, sont rejetés avant le démarrage du navigateur. Chaque agent exécuté en parallèle doit disposer de son propre Browser() : partager le même navigateur provoque une RuntimeError. En revanche, un navigateur configuré avec keep_alive=True peut être réutilisé séquentiellement (MIGRATING.md).

Migrer sans deviner : laissez les erreurs vous guider

La version 1.0 échoue volontairement au plus tôt. Les imports supprimés déclenchent un ImportError qui indique leur remplacement, les arguments Agent(...) non pris en charge une TypeError, et tout ce que la 1.0 ne peut pas honorer est signalé avant le démarrage du navigateur et toute facturation (MIGRATING.md). Un groupe plus réduit de paramètres — use_vision=True, vision_detail_level, max_actions_per_step, flash_mode, max_failures, highlight_elements et d’autres options similaires — est accepté mais ignoré, avec un avertissement pour chacun. use_vision=False conserve toutefois son effet : il empêche l’envoi des captures d’écran au modèle.

Après le démarrage, le comportement change : run() renvoie généralement un résultat en erreur au lieu de lever une exception, avec status='error' et les détails dans result.error. Seule l’annulation continue de se propager. Adaptez donc vos vérifications :

python
# 0.x
history = await agent.run(max_steps=500)
ok = history.is_successful()

# 1.0
result = await agent.run(max_steps=100)
ok = result.is_done() and result.success is not False

is_done() indique désormais uniquement que l’exécution est terminée. Le succès dépend du verdict finish(result, success) rendu par le modèle, et is_successful() renvoie None lorsque le modèle n’a fourni aucun verdict. Les anciens helpers d’historique par étape — action_names(), model_actions(), extracted_content(), save_as_playwright_script() et les autres API supprimées listées dans MIGRATING.md — ont disparu. Consultez plutôt result.messages, result.status, result.partial, les fichiers présents dans agent.workspace et result.judgement.

Commencez par trois modifications. Déplacez max_steps de Agent(...) vers agent.run(max_steps=...). Remplacez les callbacks supprimés (on_step_start, pause, stop, multi_act, save_history) par logging.getLogger('browser_use') au niveau INFO ou par BROWSER_USE_LOGGING_LEVEL=warning. Enfin, revoyez la portée des secrets. Les secrets associés à un domaine ne sont désormais typés que sur les pages correspondantes, les noms qui se terminent par bu_2fa_code sont interprétés comme des graines TOTP, et l’ancien placeholder <secret>name</secret> déclenche une erreur : il doit devenir type_secret('name'). Dans les cellules et les résultats, les valeurs sont masquées sous la forme <secret:name>. Il s’agit d’un masquage, pas d’une sandbox, puisque le code Python écrit par le modèle peut toujours les lire (MIGRATING.md). Si vous avez besoin de temps, utilisez pip install 'browser-use<1' et migrez sur une branche.

"browser use is more a python framework for building your own browsing agent" — u/Starks1293 sur r/ClaudeCode

Cette formule correspond à la manière dont des utilisateurs en parlent sur Reddit : un framework pour construire ses propres agents de navigation, souvent cité pour les sites protégés par des défenses anti-bot et pour le contrôle au niveau du code. La fiabilité dépend toujours du modèle et du site. Un retour en production décrit ainsi cinq minutes d’exécution et neuf étapes échouées pour remplir un formulaire basique.

Avant la production : évaluation, secrets et fiabilité variable

Pour les usages avancés, voici les points importants :

  • Résultats typés via output_model_schema, accessibles dans result.structured_output
  • Envoi de fichiers dans le workspace et dossier workspace/downloads, avec les téléchargements disponibles dans result.downloads
  • Contrôles de domaine (allowed_domains, prohibited_domains, block_ip_addresses) : ils encadrent un modèle correctement orienté, mais ne constituent pas une sandbox réseau
  • Recherche web activable avec web_search=True, facturée par recherche et ajoutée à result.cost_usd
  • CLI/MCP via browser-use --cli-mcp, browser-use skill install et browser-use --doctor

Considérez la 1.0 comme un framework en évolution rapide : verrouillez les versions exactes, ajoutez judge_context aux tâches longues, sauvegardez les étapes partielles avec checkpoint('titles.json', titles, partial=True) et exécutez les tâches non fiables dans des conteneurs, car les limites de domaine et le masquage des secrets ne remplacent pas une isolation (README).

Migrer maintenant, verrouiller la 1.0 ou rester en 0.x ?

SituationÀ faire
Nouveau projet d’agent, cloud acceptableCommencer avec ==1.0.7, conserver bu-4.0 par défaut et laisser l’évaluation activée
Traitements batch sensibles au coûtPasser llm='bu-fast' et judge=False, puis mesurer avant de monter en charge
Localhost / intranet / fenêtre personnaliséeUtiliser Browser('chromium') avec votre propre modèle, jamais un simple Browser()
Projet 0.x déjà en productionVerrouiller browser-use<1 sur la branche principale et migrer sur une branche en vous appuyant sur les erreurs précoces
Parcours riche en CAPTCHAPrévoir le solver dédié ; les instructions en langage naturel seules ont obtenu 0/3 dans le test de l’équipe

Vous gagnez un agent capable de bloquer un script qui ne répond plus ou d’appeler une API privée que vous n’avez jamais encapsulée, mais vous perdez les garde-fous d’un menu d’actions figé. Si ce compromis convient à votre site, migrez. Dans le cas contraire, rester sur une version verrouillée avec browser-use<1 pendant l’évaluation reste l’option la plus prudente pour un système déjà en production.

FAQ

Qu’est-ce qui change dans browser-use 1.0 ?

Un REPL Python persistant, avec les utilitaires browser-harness et le CDP brut, remplace le menu de 24 actions de la 0.x. La bibliothèque est ainsi réduite d’environ 80 %, avec un nombre de fichiers Python passé de 178 à 43. Les paramètres par défaut basculent vers Browser Use Cloud, un modèle de passerelle et une seule clé BROWSER_USE_API_KEY.

Mon code 0.x va-t-il casser ?

Les points d’entrée courants (Agent, Browser, run(), final_result()) existent toujours, mais les imports et options supprimés déclenchent un ImportError ou une TypeError avant toute facturation. max_steps a été déplacé vers run() et Browser() désigne désormais le cloud. Pour rester en 0.x, verrouillez browser-use<1 ; sinon, migrez d’abord sur une branche.

Puis-je toujours utiliser mon propre modèle et un navigateur local ?

Oui. Passez un fournisseur comme ChatOpenAI, ChatAnthropic, ChatGoogle ou une chaîne Pydantic AI, puis utilisez Browser('chromium') pour un navigateur local neuf ou Browser('chrome') pour votre Chrome déjà ouvert. Les navigateurs cloud ne peuvent pas accéder à localhost.

Quelle version de Python faut-il pour browser-use 1.0 ?

Python 3.11 ou une version ultérieure, mais inférieure à 4.0. Les versions exactes des dépendances peuvent entrer en conflit avec d’autres paquets : commencez donc par installer browser-use dans un environnement virtuel neuf.

Comment désactiver l’évaluation de l’exécution ?

Passez judge=False pour ignorer la requête d’évaluation supplémentaire, ou fournissez judge_context avec vos critères d’acceptation pour obtenir un verdict pertinent. Définissez use_vision=False si les captures d’écran utilisées par l’évaluateur ne doivent pas être envoyées.