JBrowser Source Docs

JBrowser Source Docs

This is the documentation for people who work on JBrowser's code: how it is put together, why it works the way it does, and how to build, test and release it. It covers JBrowser 1.5.3. Use the version button at the top to read the documentation of another release.

JBrowser is a desktop web browser written in Python 3.14 on PyQt6 and Qt WebEngine, which embeds Chromium. Everything you see is a Qt widget painted by JBrowser; every web page is a Chromium page that JBrowser drives through Qt's API. There is no C++ in the repository.

New here?

Start with Setting up, then read the architecture overview. The contributor quick reference is the page to keep open while you work.

Find your way#

Getting startedSet up a development environment, run JBrowser from source and make your first change. ArchitectureLayers, the dependency container, the state store, settings and commands. Web enginePer-space Chromium profiles, tab controllers, page scripts and the memory saver. Privacy and securityRequest interception, the ad-filter engine, fingerprinting, threats and the password vault. User interfaceThe window, theming, the canvas, the sidebar, the Lazy Toolbar and more. Build and releasePyInstaller, the Inno Setup installer, releases and automatic updates. Testing and qualityLinting, CI, test profiles and debugging. ReferenceEvery setting, command, shortcut and module, generated from this version's code.

JBrowser in one minute#

  • Cards on a canvas. A card is one web page. Cards sit left to right on a horizontally scrolling canvas instead of in a tab strip. See the canvas and cards.
  • Spaces. Every space has its own Chromium profile, so cookies and storage never cross between spaces. Incognito spaces keep everything in memory. See profiles and spaces.
  • One state store. BrowserState holds all spaces and cards. The web engine and every widget observe it through Qt signals and never talk to each other directly. See browser state.
  • Commands. Every action is a command with an ID, a title and optional shortcuts, so a click, a key press and the Lazy Toolbar all run the same code. See commands.
  • Privacy in the request path. Two Qt request interceptors decide, for every request, whether to block, redirect or add headers. See the request pipeline.

What's new for developers in 1.5.3#

  • jbrowser/services/adfilter.py: a token-indexed Adblock Plus filter engine for EasyList and EasyPrivacy, with element hiding. See content blocking.
  • One masked main-world privacy script replaces the separate GPC, DNT and fingerprinting scripts; hardware values are no longer spoofed, and bot-check sites are exempt. See fingerprinting and bot checks.
  • jbrowser/ui/gallery.py: the Gallery overlay. See the Gallery.
  • Colour tints in ui/theme.py, card dragging in ui/canvas.py, ui/sidebar.py and ui/window.py.

Other documentation#

  • The changelog lists every user-visible change.
  • Each folder of the repository has a README.md describing its files; they are the quickest way around the code.
  • User-facing features are listed in docs/FEATURES.md.