HTTP Backend experimental

You may install tools directly from HTTP URLs using the http backend. This backend downloads files from any HTTP/HTTPS URL and is ideal for tools that distribute pre-built binaries or archives through direct download links.

The code for this is inside of the mise repository at ./src/backend/http.rs.

Usage

The following installs a tool from a direct HTTP URL:

mise use -g http:my-tool[url=https://example.com/releases/my-tool-v1.0.0.tar.gz]@1.0.0

The version will be set in ~/.config/mise/config.toml with the following format:

[tools]
"http:my-tool" = { version = "1.0.0", url = "https://example.com/releases/my-tool-v1.0.0.tar.gz" }

Supported HTTP Syntax

• HTTP with URL parameter: http:my-tool[url=https://example.com/releases/my-tool-v1.0.0.tar.gz]@1.0.0

Tool Options

The following tool-options are available for the http backend—these go in [tools] in mise.toml.

url (Required)

Specifies the HTTP URL to download the tool from. The URL supports templating with :

[tools]
"http:my-tool" = { version = "1.0.0", url = "https://example.com/releases/my-tool-v{{version}}.tar.gz" }

You can also use static URLs without templating:

[tools]
"http:my-tool" = { version = "1.0.0", url = "https://example.com/releases/my-tool-v1.0.0.tar.gz" }

Platform-specific URLs

For tools that need different downloads per platform, use the table format:

[tools."http:my-tool"]
version = "1.0.0"

[tools."http:my-tool".platforms]
macos-x64 = { url = "https://example.com/releases/my-tool-v1.0.0-macos-x64.tar.gz" }
macos-arm64 = { url = "https://example.com/releases/my-tool-v1.0.0-macos-arm64.tar.gz" }
linux-x64 = { url = "https://example.com/releases/my-tool-v1.0.0-linux-x64.tar.gz" }

TIP

You can use either macos or darwin, and x64 or amd64 for platform keys. macos and x64 are preferred in documentation and examples, but all variants are accepted.

OS/architecture values use mise's conventions: linux, macos, windows for operating systems and x64, arm64 for architectures. For platform-specific URLs, use the appropriate platform key (e.g., macos-x64, linux-arm64) and specify the full URL for each platform.

If you mess up and use something like darwin-aarch64 mise will try to figure out what you meant and do the right thing anyhow.

checksum

Verify the downloaded file with a checksum:

[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v1.0.0.tar.gz"
checksum = "sha256:a1b2c3d4e5f6789..."

Instead of specifying the checksum here, you can use mise.lock to manage checksums.

Platform-specific Checksums

[tools."http:my-tool"]
version = "1.0.0"

[tools."http:my-tool".platforms]
macos-x64 = { url = "https://example.com/releases/my-tool-v1.0.0-macos-x64.tar.gz", checksum = "sha256:a1b2c3d4e5f6789..." }
macos-arm64 = { url = "https://example.com/releases/my-tool-v1.0.0-macos-arm64.tar.gz", checksum = "sha256:b2c3d4e5f6789..." }
linux-x64 = { url = "https://example.com/releases/my-tool-v1.0.0-linux-x64.tar.gz", checksum = "sha256:c3d4e5f6789..." }

size

Verify the downloaded file size:

[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v1.0.0.tar.gz"
size = "12345678"

Platform-specific Size

You can specify different sizes for different platforms:

[tools."http:my-tool"]
version = "1.0.0"

[tools."http:my-tool".platforms]
macos-x64 = { url = "https://example.com/releases/my-tool-v1.0.0-macos-x64.tar.gz", size = "12345678" }
macos-arm64 = { url = "https://example.com/releases/my-tool-v1.0.0-macos-arm64.tar.gz", size = "9876543" }
linux-x64 = { url = "https://example.com/releases/my-tool-v1.0.0-linux-x64.tar.gz", size = "11111111" }

strip_components

Number of directory components to strip when extracting archives:

[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v1.0.0.tar.gz"
strip_components = 1

INFO

If strip_components is not explicitly set, mise will automatically detect when to apply strip_components = 1. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., ripgrep-14.1.0-x86_64-unknown-linux-musl/rg). The auto-detection ensures the binary is placed directly in the install path where mise expects it.

bin

Rename the downloaded binary to a specific name. This is useful when downloading single binaries that have platform-specific names:

[tools."http:docker-compose"]
version = "2.29.1"
url = "https://github.com/docker/compose/releases/download/v{version}/docker-compose-linux-x86_64"
bin = "docker-compose"  # Rename from docker-compose-linux-x86_64 to docker-compose

INFO

When downloading single binaries (not archives), mise automatically removes OS/arch suffixes from the filename. For example, docker-compose-linux-x86_64 becomes docker-compose automatically. Use the bin option only when you need a specific custom name.

bin_path

Specify the directory containing binaries within the extracted archive, or where to place the downloaded file. This supports templating with :

[tools."http:my-tool"]
version = "1.0.0"
url = "https://example.com/releases/my-tool-v1.0.0.tar.gz"
bin_path = "my-tool-{{version}}/bin" # expands to my-tool-1.0.0/bin

Binary path lookup order:

1. If bin_path is specified, use that directory
2. If bin_path is not set, look for a bin/ directory in the install path
3. If no bin/ directory exists, search subdirectories for bin/ directories
4. If no bin/ directories are found, use the root of the extracted directory

Caching Behavior

The HTTP backend implements an intelligent caching system to optimize disk usage and installation speed:

Cache Location

Downloaded and extracted files are cached in $MISE_CACHE_DIR/http-tarballs/ instead of being stored separately for each tool installation. By default:

• Linux: ~/.cache/mise/http-tarballs/
• macOS: ~/Library/Caches/mise/http-tarballs/

Cache Key Generation

Cache keys are generated based on the file content to ensure identical downloads are shared across tools:

1. Blake3 hash of file content: When no checksum is provided, mise calculates a Blake3 hash of the downloaded file
2. Extraction options: strip_components is included in the cache key since it affects the extracted structure

Example cache directory structure:

~/.cache/mise/http-tarballs/
├── 71f774faa03daf1a58cc3339f8c73e6557348c8e0a2f3fb8148cc26e26bad83f/
│   ├── extracted/
│   │   └── bin/my-tool
│   └── metadata.json
└── 1c2af379bdf1fed266bc44b49271e2df5b0dafae09f1cc744b3505ec50c84719_strip_1/
    ├── extracted/
    │   └── my-tool
    └── metadata.json

Symlinked Installations

Tool installations are symlinks to the cached extracted content:

~/.local/share/mise/installs/http-my-tool/1.0.0 → ~/.cache/mise/http-tarballs/71f774.../extracted

This approach provides several benefits:

• Space efficiency: Multiple tools using the same tarball share a single cached copy
• Faster installations: Cache hits avoid re-downloading and re-extracting files
• Consistency: Identical file content always uses the same cache entry

Cache Metadata

Each cache entry includes a metadata.json file with information about the cached content:

{
  "url": "https://example.com/releases/my-tool-v1.0.0.tar.gz",
  "checksum": "sha256:a1b2c3d4e5f6789...",
  "size": 1024000,
  "extracted_at": 1703001234,
  "platform": "macos-arm64"
}

Cache Management

The HTTP backend cache follows mise's standard cache management:

• Cache entries can be cleared with mise cache clear
• The cache directory respects the MISE_CACHE_DIR environment variable
• Autopruner: mise automatically cleans up unused cache entries after 30 days of inactivity
• Manual cleanup is available with mise cache clear if needed