gtk-gnutella logo
Current version: 1.1.13



Building from source

Gnutella connections



Uploads and Sharing

GTK+ 2.x


What is gnutella anyway?

Gnutella is a decentralized Peer to Peer information exchanging network. At the moment you can publish and download files of any kind using the Gnutella network. The modern Gnutella protocol is officially documented at the GDF wiki. For more information, visit the definition of gnutella on the infoAnarchy wiki.

What is "GTKG?"

We often refer to gtk-gnutella as GTKG or gtkg (because it's shorter). GTK comes from GTK+ which is the graphical toolkit used by gtk-gnutella.

This eats up too much bandwidth!

At the moment you can try one or more of the following things if you are a user on a slow line (modem):

What are Ultrapeers and Leaf nodes?

Since version 0.92, gtk-gnutella has implemented ultrapeers and leaf nodes. This divides peers on the Gnutella network into leaf nodes, which connect only to ultrapeers, and ultrapeers, which connect to many leaf nodes and a small number of other ultrapeers (see What is a good number of connections?).

Ultrapeers must not be not firewalled, are expected to have long uptimes (more than two hours), and have sufficient surplus bandwidth to donate to the Gnutella network. Ultrapeers forward queries from their leaf nodes and leaf nodes upload to their ultrapeers QRP tables which contain hashes of keywords that will match files shared by the leaf. When an ultrapeer gets a hit on a query routing table, it relays the query to the corresponding leaf node. The result is very low Gnutella network traffic for each leaf node, freeing bandwidth for sharing and downloading (which still occur directly p2p.) Ultrapeers can also act as push-proxies for firewalled leaf nodes.

Why does gtk-gnutella claim it's firewalled when it's not?

gtk-gnutella needs to receive an incoming connection to determine if you can be reached from the outside. Until then, it's assumed that there's a firewall which blocks the configured listening TCP port. If you want to speed up the detection, use a web browser, telnet or similar and connect to the listening port from the outside. If the connection is refused or dropped, then you are very probably really unreachable due to a firewall which blocks the port, a misconfigured NAT or similar. You might want to try a different listening TCP port because some ISPs block the default Gnutella port (6346). See also, Do I need to forward a port on my firewall?.

Building from source

How do I make Configure stop asking me all those questions?

Use the script instead of Configure!

$ ./

You can set compile options on the command line too. Here is an example that will configure gtk-gnutella to

Thus, the resulting command-line looks like this: $ ./ --gtk1 --cflags="-g O0"

For available options and help regarding run this: $ ./ --help

Gnutella connections

How do I find peers?

Normally, gtk-gnutella finds peers all by itself within one or two minutes after starting it. However, if this doesn't work for you read how you can bootstrap gtk-gnutella manually and find peers to connect to.

What is a good number of connections?

In leaf mode 3 ultrapeers, in ultrapeer mode 32/40 (minimum/maximum) ultrapeers and around 100 leaf nodes. The actual number should depend on the available bandwidth. If you have set "Prefer compressed connections," bandwidth used will be much lower. You should never use up all your bandwidth with Gnutella peer connections. Especially on an asymmetric cable/DSL connection you can easily starve your incoming traffic by producing too much outgoing traffic (TCP/IP issue). Use at most half of your outgoing bandwidth for Gnutella peer connections.

Since the adoption of "high outdegree" in version 0.95 you should have 32/40 connections to other ultrapeers. The number of leaf connections to use depends on your bandwidth and the speed of your cpu. As an absolute minimum an ultrapeer should connect to 20 leaf nodes and it's much better to connect to 100 or more. Watch the bandwidth odometers on the lower left of the gui and use the top command to keep track of cpu usage. Increase the number of leaf connections until you reach the maximum amount of bandwidth and system resources you wish to devote to this purpose.

The bandwidth control settings will help you further fine-tune gtk-gnutella's bandwidth usage.

Do I need to forward a port on my firewall?

You don't need to forward any ports for gtk-gnutella to work, but it will perform much better if you do. If gtk-gnutella thinks you are firewalled, it will not show any "push" results since you wouldn't be able to download those anyway.
Even when people cannot connect directly to you, they can still download files from your node using a push request.
You can configure the port gtk-gnutella listens on. The setting Listen port is located in the Settings->Preferences->Network.

How do I configure port forwarding?

You can find instructions for most popular routers at Try to check your port forwarding.

Does gtk-gnutella use UDP?

Yes, starting with version 0.95 gtk-gnutella can also use UDP in addition to TCP. It uses the same port number for UDP and TCP.

What does "[FC]" mean?

The FC means "flow control".
In general, you should make sure that peers to which you are connected do not flow control. Watch for the trailing [FC] indication at the end of the Info string (you may need to drag the right edge past the window to trigger the underlying scroll bar), or look at the FC state in the Flags column. As a rule of thumb, if you have more than one node flow-controlling at a given time, you don't have enough outgoing bandwidth dedicated to the Gnutella network, and therefore you are harming the network: either decrease the amount of connections, enable the Prefer compressed connections option or raise the outgoing bandwidth limit.

Why do I lose Gnutella peer connections when I have an upload?

Try to do bandwidth limiting. If that doesn't help, maybe your provider throttles gnutella traffic. Try changing your gnutella port in the network settings of gtk-gnutella.

What does the stuff in the Flags column mean?

You can see the type and some of the settings of a connection here. Note push-proxies are implemented in 0.92.1c and later.

  012345678AB (offset)
  ||||||||||+ indicates a TLS-encrypted connection
  |||||||||+- hops flow triggered (h), or total query flow control (f)
  ||||||||+-- flow control (F), or pending data in queue (d)
  |||||||+--- we are push-proxy for node (P) or node is our push-proxy (p)
  ||||||+---- indicates whether Rx, Tx or both (Z) are compressed
  |||||+----- we sent our last-hop QRT to remote UP (X), or are sending one  (x)
  ||||+------ we sent/received a QRT, or are sending/receiving one (q)
  |||+------- indicates whether node is writable
  ||+-------- indicates whether node is readable
  |+--------- connection type: (Incoming, Outgoing, Ponging)
  +---------- peer mode: Ultra, Leaf, or Legacy (a.k.a. Normal)

What's the meaning of a leading "!" in the User-Agent name?

This indicates that the User-Agent name is possibly faked but it could be a false-positive caused by a bad clock on either side.

What does "Harmful version banned, upgrade required" mean?

Sometimes, peers are discovered to have a bug or behaviour that is harmful to the Gnutella network. For example, gtk-gnutella-0.92b had a bug that generated excessive queries which hammered on the GWebCache system. Such banning is exceptional, usually restricted to specific versions, and the author of the software is informed about the banning.

What does "Outdated version, please upgrade" mean?

Versions of gtk-gnutella more than one year old are banned, since they lack features that are important to the rapidly evolving health and scalability of the Gnutella network. In addition, unstable versions are banned after 90 days.

Why doesn't my HTTP proxy work?

Your HTTP proxy must support the method CONNECT because a normal GET doesn't work with Gnutella connections. This is an extension to the HTTP protocol and mainly supported by SQUID proxies. It's also often deactivated because it might be considered a security problem by your provider. At the moment, the proxy support - also for SOCKS - isn't very good. The developers don't use proxies but if you think you can fix it, we would appreciate your patches.

How can I increase the timeouts?

If your internet connection suffers from high latency it might help to increase the timeouts. Go to Settings->Preferences->User Interface and tick Expert mode. Now, you'll find a lot more settings to change when you go to Settings->Preferences->GnutellaNet.

How does auto mode decide between ultrapeer and leaf?

In order to be promoted to ultrapeer mode the following conditions must be met:

  1. There must be more than 8192 bytes/s outgoing bandwidth available.
  2. If bandwidth schedulers are enabled, leaf nodes must not be configured to steal all the HTTP outgoing bandwidth.
  3. If Gnutella network output scheduler is enabled, there must be at least 256 bytes/s per Gnutella network connection (ultrapeer or normal aka legacy).
  4. Overall, there must be 32 bytes/s per configured leaf plus 256 bytes/s per Gnutella peer connection available.

I am running as ultrapeer, why GTKG keeps struggling to reach the maximum number of connected ultrapeers while the number of connected leaves is steadily close to 100%?

There could be mainly two reasons for such behavior: 1) there is an overall shortage of ultrapeers on Gnutella network, 2) you are experiencing outgoing connection problems. The latter is the more likely explanation. When running as ultrapeer, many leaves try to connect to you. Similarly, a relatively smaller number of ultrapeers is trying to connect to you. Also, you are trying to connect to other ultrapeers but not to leaves. If your outgoing connection is poor (saturated bandwidth, provider having problems, etc) you will be unable to connect to some ultrapeers, so their IP addresses is removed from your local ultrapeer host cache. Probably you also noticed that in the cache page the regular host cache gradually reaches its maximum, while the ultrapeers hosts cache is much emptier and sometimes the number of nodes decreases instead of increasing. Actually there is not much you can do. Try to reduce the number of concurrent connections and/or the number of ultrapeers and leaves connection slots; alternatively run in leaf mode.


How can I get more results?

The number of results you get depends heavily on whether people are able to connect to you (see port forwarding) and on the number of connections to other hosts.

How can I ignore files with no SHA1?

Click with right mouse button on a search result without a SHA1 and select "Drop results...->with the same urn:sha1" from the popup menu. That will drop all results with this SHA1 - in this case none - from your results. You'll miss a lot of spam.

Where did the search entry box go?

Searches are now entered in the Search: box in the sidebar.

What are "Passive" searches?

A passive search will return all the search results that pass through gtk-gnutella. By filtering these results, passive searches can be useful.

If you are in ultrapeer mode, many search results are already passing through your node besides the ones for your own searches. You can take advantage of this to make searches without generating any extra Gnutella network traffic. For example, on my ultrapeer with 200 leaf nodes, I opened a passive search and filtered the results to display only hits with the name eminem. Within an hour or so I had about 1500 results. Obviously, the more popular the search, and the more patient you are, the more useful this technique is.

If you are in leaf mode, then the only search results that will pass through gtk-gnutella will be those from your own searches, so the above technique won't be useful. But there is another way to use passive searches that is only useful in leaf mode. For example, if you start a passive search and filter it to display only mp3 files, then all mp3 files from all your open searches will be conveniently aggregated in one search window. By opening more passive searches with different filters, you can display different file types in each.

Why are there unreadable results?

The standard encoding in the modern Gnutella network is UTF-8. All queries and results should be encoded this way. Unfortunately, there is still many legacy software that does not convert textual data (like filenames and queries) to UTF-8 but uses arbitrary character sets instead. gtk-gnutella tries to detect the used character set but this cannot be perfect. It may also replace characters with underscores if they cannot be converted to UTF-8.


What does the status "Ignoring requested [SHA1|name & size]" mean?

This means that gtk-gnutella has that file recorded as complete in its database. This database is usually located in ~/.gtk-gnutella/done.sha1 and ~/.gtk-gnutella/done.namesize. At the moment, there is no way to remove or modify an entry of that database from the gui, but you can edit the file with any text editor while gtk-gnutella is not running. If you add or remove something from one of the files, do the same to the other.

What does the status "No URN on server" mean?

This means that gtk-gnutella wants to download a new file from a host, but that host does not provide a SHA1 hash for the file. Since the file is new (not yet partially downloaded), gtk-gnutella cannot do an overlap check to verify that the file on the host is really the file you want. In such a case it relies on the SHA1 provided by the remote host, but if no SHA1 is supplied, then gtk-gnutella has no way of assuring that the file it wants to download and the file on the remote server are really the same.
If you get annoyed by those messages you can activate the Optimistic first chunk option in the Settings->Preferences->Download.

Why is the same file downloaded X times?

Check the Range column. This is called swarming. gtk-gnutella tries to get the file in chunks and will get it from multiple hosts in parallel, if possible.

What is "swarming"?

Swarming describes the ability to download a single file from multiple hosts in parallel. gtk-gnutella will automatically try to find additional sources for any queued file using the download mesh and by monitoring routed results.

What is a "chunk"?

A chunk is another word for part of a file. When gtk-gnutella runs in swarming mode it will retrieve multiple chunks of a downloading file until it has downloaded the complete file. The Range column shows you which chunk you are currently downloading.

What is the "download mesh"?

When you download a file from a host that supports the download mesh, it will tell you about additional sources for the requested file (provided it knows of any). Those will then be used for swarming

What is a "push request"?

The push request is a facility to download files from hosts you cannot connect to directly (because they are firewalled). Well, you cannot connect to those hosts, but they probably can connect to you. To tell a remote host to connect to your host so that you can download a file from the remote host you send a push request to it.
If you download a file using a push request and you loose contact to the host which originally returned the result for that file to you, then the push route is lost and you can no longer download this file. Therefore push routes are quite fragile. You can't make use of push requests when you are behind a firewall (see port forwarding).

Why does gtk-gnutella append a .OK to my file names?

You probably haven't set up different directories for downloaded files, temporary files and bad files.

I got a file that just won't download!

If you don't see a smiling yellow icon with sunglasses in the statusbar, you should try to change that. See the section about firewalls.

Otherwise if gtk-gnutella says it has only a few sources for the file (best seen in the fileinfo subtab in the downloads pane) then this can have two reasons:

You can try to search for the file again and see if you find another version which is more common. It's usually a good indication if the "#" shows a number for a file. The larger the number, the better are the chances that you can get it quickly.

In the downloads pane, what does it mean if the color of the text is grey instead of black?

It means that the file is received over a push route.

What is the filename encoding?

gtk-gnutella uses UTF-8 as default encoding for filenames. If your locale setting does not use UTF-8, other applications may not display these filenames correctly or may have problems accessing them in the worst case. You can change the encoding using the environment variable G_FILENAME_ENCODING. This affects most applications that use Gtk+ or GLib.

If your system does not use UTF-8, it is recommend to use either G_FILENAME_ENCODING="UTF-8,@locale,ISO-8859-1" or G_FILENAME_ENCODING="@locale,UTF-8,ISO-8859-1" .

The first item in the list is the encoding used to store files. Following items are character sets used to convert existing filenames as found on the disk to UTF-8 for display purposes and information exchange. For people from Western Europe it is recommendable to add ISO-8859-1 as shown above to the list if you share any files that contain non-ASCII characters and which are encoded as ISO-8859-1 characters. For people from other regions of the world, other character sets might be more appropriate.

In most cases, the special item "@locale" takes care of this. This stands for the encoding used by the current locale and it's very likely that filenames are encoded with it. You can list multiple secondary filename character sets. When converting filenames to UTF-8, the first successful conversion will be used. The character sets are tried in the listed order. Non-convertible characters are replaced with underscores. This means if you download a file with mostly Arabic or Japanese characters in it, converting the filename to ASCII or ISO-8859-1 strips most or all information from the filename. Therefore it's best to stick with UTF-8.

gtk-gnutella supports G_FILENAME_ENCODING since version 0.96 regardless whether you use Gtk+ 1.2 or Gtk+ 2.x as front-end.

Uploads and Sharing

What does "Normalized" mean?

This shows the total amount of bytes uploaded for the file divided by the file size.

Why not all files within the shared folders are being shared?

By default Gtk-Gnutella shares only the files whose extension is included in the Search extensions below the shared folders list in the Preferences. If your files are not being shared, probably their extension is not included in that list. There are 2 ways to solve this issue:

  1. include the extensions of the unshared files in the Search extensions list;
  2. replace the whole list of extensions with the wildcard "--all--".

Please note that you can check which files are being shared locally on your host by doing a search with the wildcard "local:".

GTK+ 2.x

Non-ASCII characters show up as _ (underscore).

Set the environment variable LC_CTYPE or LC_ALL to an appropriate value for the encoding you use. For example, if you use special German characters in your filenames, set it to de_DE.ISO8859-1. The valid values depend on your operating system, see the manpage setlocale(3) for details. Ideally, everyone would use UTF-8 encoding which covers nearly all languages Logo   Glade   RSS Feed Available   Ohloh Metrics   Coverity Scan Build Status   gtk-gnutella at GitHub  
gtk-gnutella © 2000-2014 by Yann Grossel, Raphaël Manfredi and various contributors.