1:mod:`webbrowser` --- Convenient web-browser controller
2=======================================================
3
4.. module:: webbrowser
5   :synopsis: Easy-to-use controller for web browsers.
6
7.. moduleauthor:: Fred L. Drake, Jr. <[email protected]>
8.. sectionauthor:: Fred L. Drake, Jr. <[email protected]>
9
10**Source code:** :source:`Lib/webbrowser.py`
11
12--------------
13
14The :mod:`webbrowser` module provides a high-level interface to allow displaying
15web-based documents to users. Under most circumstances, simply calling the
16:func:`.open` function from this module will do the right thing.
17
18Under Unix, graphical browsers are preferred under X11, but text-mode browsers
19will be used if graphical browsers are not available or an X11 display isn't
20available.  If text-mode browsers are used, the calling process will block until
21the user exits the browser.
22
23If the environment variable :envvar:`BROWSER` exists, it is interpreted as the
24:data:`os.pathsep`-separated list of browsers to try ahead of the platform
25defaults.  When the value of a list part contains the string ``%s``, then it is
26interpreted as a literal browser command line to be used with the argument URL
27substituted for ``%s``; if the part does not contain ``%s``, it is simply
28interpreted as the name of the browser to launch. [1]_
29
30For non-Unix platforms, or when a remote browser is available on Unix, the
31controlling process will not wait for the user to finish with the browser, but
32allow the remote browser to maintain its own windows on the display.  If remote
33browsers are not available on Unix, the controlling process will launch a new
34browser and wait.
35
36The script :program:`webbrowser` can be used as a command-line interface for the
37module. It accepts a URL as the argument. It accepts the following optional
38parameters: ``-n`` opens the URL in a new browser window, if possible;
39``-t`` opens the URL in a new browser page ("tab"). The options are,
40naturally, mutually exclusive.  Usage example::
41
42   python -m webbrowser -t "https://www.python.org"
43
44.. include:: ../includes/wasm-notavail.rst
45
46The following exception is defined:
47
48
49.. exception:: Error
50
51   Exception raised when a browser control error occurs.
52
53The following functions are defined:
54
55
56.. function:: open(url, new=0, autoraise=True)
57
58   Display *url* using the default browser. If *new* is 0, the *url* is opened
59   in the same browser window if possible.  If *new* is 1, a new browser window
60   is opened if possible.  If *new* is 2, a new browser page ("tab") is opened
61   if possible.  If *autoraise* is ``True``, the window is raised if possible
62   (note that under many window managers this will occur regardless of the
63   setting of this variable).
64
65   Note that on some platforms, trying to open a filename using this function,
66   may work and start the operating system's associated program.  However, this
67   is neither supported nor portable.
68
69   .. audit-event:: webbrowser.open url webbrowser.open
70
71
72.. function:: open_new(url)
73
74   Open *url* in a new window of the default browser, if possible, otherwise, open
75   *url* in the only browser window.
76
77.. function:: open_new_tab(url)
78
79   Open *url* in a new page ("tab") of the default browser, if possible, otherwise
80   equivalent to :func:`open_new`.
81
82
83.. function:: get(using=None)
84
85   Return a controller object for the browser type *using*.  If *using* is
86   ``None``, return a controller for a default browser appropriate to the
87   caller's environment.
88
89
90.. function:: register(name, constructor, instance=None, *, preferred=False)
91
92   Register the browser type *name*.  Once a browser type is registered, the
93   :func:`get` function can return a controller for that browser type.  If
94   *instance* is not provided, or is ``None``, *constructor* will be called without
95   parameters to create an instance when needed.  If *instance* is provided,
96   *constructor* will never be called, and may be ``None``.
97
98   Setting *preferred* to ``True`` makes this browser a preferred result for
99   a :func:`get` call with no argument.  Otherwise, this entry point is only
100   useful if you plan to either set the :envvar:`BROWSER` variable or call
101   :func:`get` with a nonempty argument matching the name of a handler you
102   declare.
103
104   .. versionchanged:: 3.7
105      *preferred* keyword-only parameter was added.
106
107A number of browser types are predefined.  This table gives the type names that
108may be passed to the :func:`get` function and the corresponding instantiations
109for the controller classes, all defined in this module.
110
111+------------------------+-----------------------------------------+-------+
112| Type Name              | Class Name                              | Notes |
113+========================+=========================================+=======+
114| ``'mozilla'``          | :class:`Mozilla('mozilla')`             |       |
115+------------------------+-----------------------------------------+-------+
116| ``'firefox'``          | :class:`Mozilla('mozilla')`             |       |
117+------------------------+-----------------------------------------+-------+
118| ``'netscape'``         | :class:`Mozilla('netscape')`            |       |
119+------------------------+-----------------------------------------+-------+
120| ``'galeon'``           | :class:`Galeon('galeon')`               |       |
121+------------------------+-----------------------------------------+-------+
122| ``'epiphany'``         | :class:`Galeon('epiphany')`             |       |
123+------------------------+-----------------------------------------+-------+
124| ``'skipstone'``        | :class:`BackgroundBrowser('skipstone')` |       |
125+------------------------+-----------------------------------------+-------+
126| ``'kfmclient'``        | :class:`Konqueror()`                    | \(1)  |
127+------------------------+-----------------------------------------+-------+
128| ``'konqueror'``        | :class:`Konqueror()`                    | \(1)  |
129+------------------------+-----------------------------------------+-------+
130| ``'kfm'``              | :class:`Konqueror()`                    | \(1)  |
131+------------------------+-----------------------------------------+-------+
132| ``'mosaic'``           | :class:`BackgroundBrowser('mosaic')`    |       |
133+------------------------+-----------------------------------------+-------+
134| ``'opera'``            | :class:`Opera()`                        |       |
135+------------------------+-----------------------------------------+-------+
136| ``'grail'``            | :class:`Grail()`                        |       |
137+------------------------+-----------------------------------------+-------+
138| ``'links'``            | :class:`GenericBrowser('links')`        |       |
139+------------------------+-----------------------------------------+-------+
140| ``'elinks'``           | :class:`Elinks('elinks')`               |       |
141+------------------------+-----------------------------------------+-------+
142| ``'lynx'``             | :class:`GenericBrowser('lynx')`         |       |
143+------------------------+-----------------------------------------+-------+
144| ``'w3m'``              | :class:`GenericBrowser('w3m')`          |       |
145+------------------------+-----------------------------------------+-------+
146| ``'windows-default'``  | :class:`WindowsDefault`                 | \(2)  |
147+------------------------+-----------------------------------------+-------+
148| ``'macosx'``           | :class:`MacOSXOSAScript('default')`     | \(3)  |
149+------------------------+-----------------------------------------+-------+
150| ``'safari'``           | :class:`MacOSXOSAScript('safari')`      | \(3)  |
151+------------------------+-----------------------------------------+-------+
152| ``'google-chrome'``    | :class:`Chrome('google-chrome')`        |       |
153+------------------------+-----------------------------------------+-------+
154| ``'chrome'``           | :class:`Chrome('chrome')`               |       |
155+------------------------+-----------------------------------------+-------+
156| ``'chromium'``         | :class:`Chromium('chromium')`           |       |
157+------------------------+-----------------------------------------+-------+
158| ``'chromium-browser'`` | :class:`Chromium('chromium-browser')`   |       |
159+------------------------+-----------------------------------------+-------+
160
161Notes:
162
163(1)
164   "Konqueror" is the file manager for the KDE desktop environment for Unix, and
165   only makes sense to use if KDE is running.  Some way of reliably detecting KDE
166   would be nice; the :envvar:`KDEDIR` variable is not sufficient.  Note also that
167   the name "kfm" is used even when using the :program:`konqueror` command with KDE
168   2 --- the implementation selects the best strategy for running Konqueror.
169
170(2)
171   Only on Windows platforms.
172
173(3)
174   Only on macOS platform.
175
176.. versionadded:: 3.3
177   Support for Chrome/Chromium has been added.
178
179.. deprecated-removed:: 3.11 3.13
180   :class:`MacOSX` is deprecated, use :class:`MacOSXOSAScript` instead.
181
182Here are some simple examples::
183
184   url = 'https://docs.python.org/'
185
186   # Open URL in a new tab, if a browser window is already open.
187   webbrowser.open_new_tab(url)
188
189   # Open URL in new window, raising the window if possible.
190   webbrowser.open_new(url)
191
192
193.. _browser-controllers:
194
195Browser Controller Objects
196--------------------------
197
198Browser controllers provide these methods which parallel three of the
199module-level convenience functions:
200
201
202.. attribute:: name
203
204   System-dependent name for the browser.
205
206
207.. method:: controller.open(url, new=0, autoraise=True)
208
209   Display *url* using the browser handled by this controller. If *new* is 1, a new
210   browser window is opened if possible. If *new* is 2, a new browser page ("tab")
211   is opened if possible.
212
213
214.. method:: controller.open_new(url)
215
216   Open *url* in a new window of the browser handled by this controller, if
217   possible, otherwise, open *url* in the only browser window.  Alias
218   :func:`open_new`.
219
220
221.. method:: controller.open_new_tab(url)
222
223   Open *url* in a new page ("tab") of the browser handled by this controller, if
224   possible, otherwise equivalent to :func:`open_new`.
225
226
227.. rubric:: Footnotes
228
229.. [1] Executables named here without a full path will be searched in the
230       directories given in the :envvar:`PATH` environment variable.
231