PyBitmessage Help

From Bitmessage Wiki
Jump to navigation Jump to search

Welcome to the help page for PyBitmessage.

Main window in Windows 8 and newer


PyBitmessage is the official client, used as protocol reference. It is usually abbreviated "Bitmessage", causing confusion between the protocol and the client.

Initial setup

PyBitmessage can be downloaded from the Main Page, either as Windows binary or as source from github. Other builds (for example for Mac OS X) can be found in the forum. The client sets up itself completely automatic. It can be launched and the required files for its operation are created if they do not exist.

Daily usage

Main window with sent tab open (Windows 7)

PyBitmessage will automatically connect to other clients on start up, the user does not needs to wait for this to complete and can instantly send messages. POW can be made if offline. The Main interface contains the following tabs:


The inbox contains all your received messages (top part) and displays the currently selected message (bottom part). The bottom window allows copying and editing the message but it will not be saved. The context menu in the message list provides additional features, such as HTML view, save as text file and a reply option. Using the HTML view renders some HTML tags from the message, for example images. Messages that are no longer needed can be sent to the trash with the [DEL] key.


The "Send" tab is used to compose new private or Broadcast messages. A message can be dedicated to multiple people but the protocol supports only one receiving address per message. Example: Sending a message to 8 people will generate the exact same message 8 times in the "Sent" tab.


The sent tab displays messages sent by the user, including messages that are in the process of proof of work. The status column displays the current status of the message. Table with the most common messages:

Status Description
Doing work necessary to send <type>... POW is being done
<type> sent on <date/time> The message has been sent
Waiting on Acknowledgement The message has been sent but the receiver has not received it yet. Not applicable for broadcasts
Acknowledgement received on <date+time> The receiver got the message. Not applicable for broadcasts

Messages can be sent to the trash with the [DEL] key however, this will not stop POW from being made if it has already started.

Your Identities

Contains a list of all addresses stored in keys.dat and allows to generate new ones. The context menu allows to enable/disable addresses. Addresses can be labeled, this label is then displayed instead of the address. Labels are not sent over the network and are only visible to the client. Addresses cannot be deleted directly in this tab, but removing the Address Block from keys.dat removes it. Editing the keys.dat file requires the user to shut down the client first.


Contains a list of all broadcasts, that the client will receive. To receive broadcasts its address must be added first to the list. The context menu allows enabling, disabling and deletation of addresses.

Address Book

Can be used to associate addresses with labels for easier recognition. The context menu allows the user to add a subscription to the address.


Addresses can be blacklisted or whitelisted. The Operation mode of the list (whitelist or blacklist) ban be set too. The context menu allows entries to be enabled, disabled or deleted.

Network Status

Shows the Stream number and the number of connected nodes in a list. Displays when it was started and how much information has been processed yet. Detailed information about the icon color and how to get a green icon can be found here

DML Addresses

Joining a DML by using passphrase and address

A DML Address can be either created or joined in the File > Join / Create chan menu. These addresses are written with orange color in the identities tab.

To learn more about how to use a DML Address / chan, visit this article. You need to either create the address or join it to send messages to it, else the client gets stuck when waiting for the public key. To resolve this issue, without joining or creating an address see, the DML article.


To Join a DML, the address and the passphrase is required. The passphrase is used to generate the private keys, that the client needs to send and receive messages. The address is used so the user does not needs to know the stream number and address version. If the address is not known, a DML can be created, even if it actually exists, in the hope, that the resulting address is correct.


Creating a DML/chan only requires a passphrase. It will create the address and mark it as such.


There is no technical difference between creation and joining. Joining requires the address to make sure, you actually get the correct private keys, because they depend on stream number and address version, which are both included in the address. Creating an address however will always use the newest address version and stream number and thus may create a different address, which is not compatible with the one intended to join.


Bitmessage can be configured by editing keys.dat or by using the menu Settings > Settings in the GUI.

Settings Menu

The settings menu has the folowing tabs:

User Interface

Allows customization how bitmessage is started and if it should run in portable mode or not.

Willingly include...

Willingly include unencrypted destination address when sending to a mobile device

This option must be enabled, when using DML addresses and is a work in progress feature for mobile app support and has nothing to do with the user interface.

Interface language

This option is currently (at least in the compiled windows version) not fully working but allows to set the language of the client.

Network Settings

Allows setting of the TCP port used for incomming connections. This can be left at default value for most users. A proxy server can be defined if the user wishes to do so. Supports SOCKS4a and SOCKS5 with Authentication support. The option to allow incoming connections can be enabled if the user wishes to help the network, even when using a proxy. Incoming connections are not routed over the socks proxy!

Demanded Difficulty

The demanded difficulty allows to increase the amount of POW to be done for other clients to send messages to the user. POW for users in the address book is always 1. Doubling the number doubles the amount of time required.

The value for small difficulty defaults to 1.0, rthe value for large difficulty to 2.0 (since version 0.4.0)

Max acceptable difficulty

Similar to the "demanded difficulty" tab, this tab has the exact same textboxes, however, they are used to limit the amount of POW the user is willing to do. If he sends a message and the destination address wants him to do more POW than he set as maximum, the message will not be processed. The user can click with the right mouse button on the message and force it to be sent or he can delete the message.

Database cleanup

The database (messages.dat) can be cleaned and shrinked manually with the menu File > Delete all trashed messages. The database is compacted once every month automatically without deletion of trashed messages.



On an average computer, different processes take different amounts of time.

Action Time required
Generate an address 1 second*
Generate an address (1 or 2 characters shorter) 5 minutes*
Sender do work necessary to send broadcast 2 minutes
Sender do work necessary to send person-to-person message 4 minutes
message (or acknowledgement data) propagate through the network 10 seconds

Note that on Linux and OSX systems, Bitmessage can often do work much faster as it is able to use all available cores and a faster hashing module.

* After this step is done, the client will silently do work to send out the public key over the network which will take about 2 minutes.