Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Developer and designing mailing list
OnionShare has a mailing list for developers and and designers to discuss the project. You can subscribe here: https://lists.riseup.net/www/subscribe/onionshare-dev
To get started developing for OnionShare, you should clone this repo, and then consult the BUILD.md 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
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 127.0.0.1 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.
BUILD.md 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.
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 | https://onionshare.org/ [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] TorConnectionThread.run [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] UpdateThread.run [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 http://127.0.0.1:17620/ (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
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 BUILD.md instructions).
After this, you can run
onionshare-gui.exe --debug from a cmd.exe to obtain debug output of the running GUI process.
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.