Developing OnionShare

Miguel Jacq edited this page Sep 18, 2018 · 5 revisions

Developer and designing mailing list

OnionShare has a mailing list for developers and and designers to discuss the project. You can subscribe here:

Getting started

To get started developing for OnionShare, you should clone this repo, and then consult the page. That page contains the technical instructions and commands necessary to install dependencies, depending on your platform.

Running OnionShare without making a package

Onionshare comes with some convenient wrapper dev scripts. These make it easy to start the application without first packaging up a binary for it.

The scripts come in two forms: command-line only, and a GUI version.

The scripts can be found within the ./dev_scripts/ folder.

For example, to start the GUI based on the current source code in your working copy:


Note that the dev scripts do not support 'bundled tor' mode when running on Windows or macOS. Instead, you should start Tor Browser in the background, or use a system tor. For more information see Connecting to Tor.

If using Debian Jessie, bundled Tor will work if you obtain newer Tor and Stem - see the Linux Distribution Support page.

There is also the option to not use Tor at all, by passing the --local-only flag. When in local-only mode, the web server is instead set up as a simple local server (still bound to and a random high-numbered port) rather than a Hidden Service reachable via the Tor network.

You can use --help to obtain info on other available flags.

Making a package

You can also package up your working version into a bundled app, by running one of the relevant 'build' scripts located in the install directory. For example, on a Mac:


The resulting package is now available in the dist/ subfolder and can be executed as follows:


If you subsequently modify a .py file, re-running the install script will detect the changed file and re-bundle up the necessary bits. Or to completely re-bundle (which on macOS would then mean re-downloading Tor from the Tor Browser dmg), you can remove the dist dir and re-run the script.

See for instructions in Windows and macOS.


When developing, it's convenient to add the --debug flag to either the dev script (see above), or as an arg to your packaged version.

./dist/ --debug

This flag prints a lot of helpful messages to stdout, such as when certain objects are initialized, when events occur (such as buttons clicked, settings saved or reloaded), and flags sent to functions such as starting the onion web server.

Miguels-MacBook-Pro:onionshare miguel$ ./dev_scripts/onionshare-gui  --debug
Onionshare 1.1.dev1 |
[May 23 2017 10:18:54] Onion.__init__
[May 23 2017 10:18:54] OnionShare.__init__
[May 23 2017 10:18:54] OnionShareGui.__init__
[May 23 2017 10:18:54] Settings.__init__
[May 23 2017 10:18:54] Settings.load
[May 23 2017 10:18:55] TorConnectionDialog.__init__
[May 23 2017 10:18:55] TorConnectionDialog.start
[May 23 2017 10:18:55] TorConnectionThread.__init__
[May 23 2017 10:18:55]
[May 23 2017 10:18:55] Onion.connect
[May 23 2017 10:18:56] TorConnectionDialog._connected_to_tor
[May 23 2017 10:18:56] UpdateThread.__init__
[May 23 2017 10:18:56]
[May 23 2017 10:18:56] UpdateChecker.__init__
[May 23 2017 10:18:56] UpdateChecker.check: force=False
[May 23 2017 10:18:56] Settings.__init__
[May 23 2017 10:18:56] Settings.load
[May 23 2017 10:19:01] OnionShareGui.start_server
[May 23 2017 10:19:01] OnionShare.set_stealth: stealth=False
[May 23 2017 10:19:01] OnionShare.start_onion_service
[May 23 2017 10:19:01] Onion.start_onion_service
Configuring onion service on port 17620.
Starting ephemeral Tor onion service and awaiting publication
[May 23 2017 10:19:44] OnionShareGui.start_server_step2
 * Running on (Press CTRL+C to quit)
[May 23 2017 10:19:44] OnionShareGui.start_server_step3
[May 23 2017 10:19:44] OnionShareGui.copy_url

You can add your own debug messages by implementing the 'log' function from onionshare/common e.g:

common.log('OnionShareGui', 'start_server', 'I ran here')

This can be useful when learning the chain of events that occur when using the application or the value of certain variables before and after they are manipulated.

Debugging on Windows

If you want to obtain debug output from the onionshare-gui.exe on Windows, you will need to edit install\pyinstaller.spec and change console=False to console=True

Then rebuild the exe with install\build_exe.bat (you may need to comment out the signtool commands in the build_exe.bat as well as the onionshare.nsi files, as per the instructions).

After this, you can run onionshare-gui.exe --debug from a cmd.exe to obtain debug output of the running GUI process.

Writing tests

OnionShare is in the process of implementing QtTest/unittest (for GUI tests), and pytest for actually running these as well as CLI tests.

This is a work in progress. To help out or keep up to date on developments, watch this ticket.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.