# How to Throttle Upload Speed in Croc Transfers

> Learn to throttle upload speed in croc transfers using the --throttleUpload flag. Control bandwidth easily with human-readable units like 500k or 2M for efficient file transfers.

- Repository: [Zack/croc](https://github.com/schollz/croc)
- Tags: how-to-guide
- Published: 2026-07-26

---

**Croc provides the `--throttleUpload` flag to cap outgoing bandwidth using human-readable units like `500k`, `2M`, or `1G`, leveraging the `golang.org/x/time/rate` package to enforce limits during each file transfer.**

Croc is a secure, peer-to-peer file transfer tool written in Go that prioritizes simplicity and cross-platform compatibility. When sharing large files over limited bandwidth connections, you can throttle upload speed in croc transfers to prevent network saturation and maintain usable internet access for other applications. This functionality parses suffixed values and applies a token-bucket rate limiter to the outgoing data stream.

## Using the --throttleUpload Flag

To limit upload bandwidth, append `--throttleUpload` followed by a numeric value and an optional unit suffix. If you omit the suffix, croc interprets the value as bytes per second.

### Supported Size Units

Croc recognizes standard binary suffixes to scale the throttle value appropriately:

- **`k` or `K`**: Kilobytes (1024 bytes per second)
- **`M`**: Megabytes (1024² bytes per second)
- **`G`**: Gigabytes (1024³ bytes per second)

### Practical Command Examples

```bash

# Limit upload to ~500 KB/s

croc send --throttleUpload 500k large-file.iso

# Limit to 2 MiB/s when sending folders

croc send --throttleUpload 2M big-folder/

# Limit to 1 GiB/s (useful for testing on fast LANs)

croc send --throttleUpload 1G huge-dataset.tar

# Specify raw bytes for precise control (100 KB/s = 102400 bytes)

croc send --throttleUpload 102400 document.pdf

```

## How Rate Limiting Works in the Source Code

According to the croc source code, the throttling mechanism spans the command-line interface layer and the core client logic, utilizing Go’s standard rate limiting library to govern packet transmission.

### CLI Flag Definition

In [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) at lines 156-158, the `--throttleUpload` flag is defined to accept a string value representing the desired bandwidth cap. This value is passed into the client configuration during initialization.

### Parsing and Limiter Creation

In [`src/croc/croc.go`](https://github.com/schollz/croc/blob/main/src/croc/croc.go) between lines 258-288, croc parses the throttle string and applies the appropriate byte multiplier based on the detected suffix. The code instantiates a `rate.NewLimiter` from the `golang.org/x/time/rate` package (declared in `go.mod`) and attaches it to the `Client` struct field `c.limiter`.

### Runtime Enforcement

During file transmission, croc consults `c.limiter` before dispatching data chunks. The limiter’s `ReserveN` method calculates the necessary delay to maintain the specified rate, pausing execution until the bandwidth budget allows the next chunk to proceed. This token-bucket algorithm ensures the upload rate never exceeds the configured threshold while smoothing out burst traffic.

## Summary

- Use `--throttleUpload` with values like `500k`, `2M`, or `1G` to throttle upload speed in croc transfers.
- The flag is defined in [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) (lines 156-158) and processed in [`src/croc/croc.go`](https://github.com/schollz/croc/blob/main/src/croc/croc.go) (lines 258-288).
- Croc utilizes `golang.org/x/time/rate` to create a token-bucket rate limiter stored in `c.limiter` that enforces caps via `ReserveN`.
- Omitting unit suffixes interprets the value as raw bytes per second.

## Frequently Asked Questions

### What units does --throttleUpload support?

The `--throttleUpload` flag supports `k` or `K` for kilobytes, `M` for megabytes, and `G` for gigabytes per second. Without a suffix, the value is treated as bytes per second. For example, `--throttleUpload 500k` limits the transfer to approximately 500 kilobytes per second, while `102400` equals 100 KB/s.

### How does croc implement the upload throttle internally?

The implementation resides in [`src/croc/croc.go`](https://github.com/schollz/croc/blob/main/src/croc/croc.go) where the flag value is parsed between lines 258-288. The code creates a `rate.NewLimiter` from the `golang.org/x/time/rate` package and attaches it to `c.limiter`. During transfers, the `ReserveN` method pauses execution to enforce the specified bandwidth cap.

### Can I throttle download speed separately from upload speed?

While the source analysis focuses on `--throttleUpload`, croc typically provides separate flags for download throttling. Check the latest [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) for `--throttleDownload` or similar options, as the architecture supports distinct rate limiters for each transfer direction.

### What happens if I specify a raw number without units?

If you omit the unit suffix, croc interprets the value as bytes per second. For example, `--throttleUpload 102400` sets the limit to exactly 102,400 bytes per second (100 KB/s), providing precise control when human-readable suffixes are not required.