# Installation

## Getting Started

First, install the `camoufox` package:

```bash
pip install -U "camoufox[geoip]"
```

The `geoip` parameter is optional, but heavily recommended if you are using proxies. It will download an extra dataset to determine the user's longitude, latitude, timezone, country, & locale.

Next, download the Camoufox browser:

+++ Windows

```bash
python -m camoufox fetch
```

+++ MacOS & Linux

```bash
python3 -m camoufox fetch
```

+++

To uninstall, run `camoufox remove`.

---

# Managing multiple Camoufox versions

Install multiple versions of Camoufox from multiple repositories and switch between them as needed.

## UI Manager

### Installing

To use the Qt UI manager, install the `[gui]` extra:

```bash
pip install -U "camoufox[gui]"
```

### Usage

Launch it with:

```bash
camoufox gui
```

Here you can manage installed browsers, active version, IP geolocation databases, and package info.

<img width="802" height="552" alt="ui-screenshot" src="../../static/python-ui-manager.png" />

<br>
<br>

!!! Instructions
- The item marked as **Active** is the browser that will be launched when starting Camoufox.
- You can pin a version by clicking the :icon-pin: icon next to it. To follow a channel's latest releases instead, click the :icon-pin: icon next to the channel name on the left. By default, the **Official** channel is followed.
!!!

---

## CLI Manager

Six commands cover the whole workflow:

| Command | Description |
|---|---|
| `camoufox sync` | Refreshes the list of available versions |
| `camoufox set` | Chooses the active target |
| `camoufox active` | Shows active target |
| `camoufox fetch` | Installs active target |
| `camoufox list` | Shows what's installed |
| `camoufox remove` | Delete a specific version |

---

### Demonstration

<video src="../../static/python-cli-manager.mp4" controls style="max-width: 100%;"></video>

<details>
<summary>See help message</summary>

```
$ python -m camoufox --help

 Usage: python -m camoufox [OPTIONS] COMMAND [ARGS]...

╭─ Options ─────────────────────────────────────────────────────────────────────────────╮
│ --help  Show this message and exit.                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────────────────────╮
│ active    Print the current active version                                            │
│ fetch     Install the active version, or a specific version                           │
│ gui       Launch the Camoufox Manager GUI (requires PySide6)                          │
│ list      List Camoufox versions                                                      │
│ path      Print the install directory path                                            │
│ remove    Remove downloaded data. By default, this removes everything.                │
│           Pass --select to pick a browser version to remove.                          │
│ server    Launch a Playwright server                                                  │
│ set       Set the active Camoufox version to use & fetch.                             │
│           By default, this opens an interactive selector for versions and settings.   │
│           You can also pass a specifier to activate directly:                         │
│           Pin version:                                                                │
│               camoufox set official/stable/134.0.2-beta.20                            │
│           Automatically find latest in a channel source:                              │
│               camoufox set official/stable                                            │
│ sync      Sync available versions from remote repositories                            │
│ test      Open the Playwright inspector                                               │
│ version   Display version, package, browser, and storage info                         │
╰───────────────────────────────────────────────────────────────────────────────────────╯
```

</details>

<hr width=50>

### Sync with upstream repositories

Pull a list of release assets from GitHub.

```bash
> camoufox sync
Syncing repositories...
  Official... 24 versions
  CoryKing... 2 versions

Synced 26 versions from 2 repos.
```

<hr width=50>

### Set active version

Choose the active browser: follow a channel, or pin a specific version. Can also be called with a specifier to activate directly.

The active target is either a channel or an exact version:

| You set | Mode | `camoufox fetch` installs |
|---|---|---|
| `official/stable` | **Following** a channel | The newest release in that channel, each time |
| `official/stable/134.0.2-beta.20` | **Pinned** to a version | Exactly that version, every time |

Same string, but add the version to pin it. By default, Camoufox follows `official/stable`.

Open an interactive selector TUI:

```bash
> camoufox set
```

Follow a channel (each [fetch](#fetch-the-active-item) will pull its latest release):

```bash
> camoufox set official/stable  # Default setting
```

Follow the latest prerelease:
<br><sub>(This applies to releases marked as prelease in GitHub or named "alpha")</sub>

```bash
> camoufox set official/prerelease
```

Pin a specific version:

```bash
> camoufox set official/stable/134.0.2-beta.20
```

<hr width=50>

### Show active version

Prints the current active version string:

```bash
> camoufox active  # Following the default channel
official/stable
```

```bash
> camoufox set coryking/stable/142.0.1-fork.26
Pinned: coryking/stable/142.0.1-fork.26
Run 'camoufox fetch' to install.

> camoufox active  # A specific version is pinned
coryking/stable/142.0.1-fork.26 (not installed)
```

<hr width=50>

### Fetch the active item

Installs whatever is **active**. This will also automatically sync repository assets.

```bash
> camoufox fetch
# By default, this installs the latest release in official/stable, since "official/stable" is active.
```

To follow a different channel:

```bash
> camoufox set coryking/stable
> camoufox fetch  # Will download the latest release from CoryKing's repo from now on
```

Or pass in the identifier to download directly without activating it:

```bash
> camoufox fetch official/stable/135.0-beta.25   # Install a specific version
```

<hr width=50>

### List downloads

List installed or all available Camoufox versions as a tree.

```bash
> camoufox list          # show installed versions
> camoufox list all      # show all available versions from synced repos
> camoufox list --path   # show full install paths
```

<hr width=50>

### Remove an item

By default, removes the entire camoufox data directory.

```bash
> camoufox remove
> camoufox remove -y  # skip confirmation prompt
```

Remove a specific version:

```bash
> camoufox remove official/stable/134.0.2-beta.20
```

Interactively select a version to remove:

```bash
> camoufox remove --select
```

---

## Debugging

### Manually open Camoufox

Use this to open Camoufox with the Playwright inspector for debugging/testing page behavior. Camoufox is not meant for human use, so please expect the window resizing and browser fonts to be broken.

```bash
> camoufox test
> camoufox test https://example.com
```

---

### Package info

Display the Python package version, active browser version, channel, and update status. This is useful if you are submitting an [issue](https://github.com/daijro/camoufox/issues).

```bash
> camoufox version
Python Packages
  Camoufox                    v0.5.0
  Browserforge                v1.2.4
  Apify Fingerprints          v0.10.0
  Playwright                  v1.57.1.dev0+g732639b35.d20251217
Browser
  Active                      official/stable/135.0.1-beta.24
  Current browser             v135.0.1-beta.24
  Installed                   Yes
  Latest in official/stable?  Yes
  Last Sync                   2026-03-07 00:23
GeoIP
  Database                    MaxMind GeoLite2
  Updated                     2026-03-07 00:24
Storage
  Install path                /home/name/.cache/camoufox
  Browser(s) directory size   1.2 GB
  GeoIP database size         40.7 MB
  Config file                 /home/name/.cache/camoufox/config.json
  Repo cache                  /home/name/.cache/camoufox/repo_cache.json
```

<hr width=50>

Print the install directory path.

```bash
> camoufox path
/home/name/.cache/camoufox
```
