> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/user-guide/installation/manual-path-setup.md).

# Manual PATH Setup

If the automatic PATH configuration fails during Orbitron installation, follow this guide to set it up manually.

## Why is PATH Configuration Needed?

Orbitron is installed in the `~/.local/bin/` directory. To use the `orbitron` command directly from your terminal, this path must be registered in your system PATH.

Without PATH configuration:

* You'll get a "command not found" error when running `orbitron`
* You'll need to type the full path (`~/.local/bin/orbitron`) every time
* If an older version exists in a different path, that version may run instead

***

## macOS / Linux

### Zsh (macOS Default Shell)

1. **Open the configuration file:**

```bash
nano ~/.zshrc
```

2. **Add the following line at the top of the file:**

```bash
export PATH="$HOME/.local/bin:$PATH"
```

3. **Save and exit:** `Ctrl + O` → `Enter` → `Ctrl + X`
4. **Apply the configuration:**

```bash
source ~/.zshrc
```

5. **Verify installation:**

```bash
orbitron --version
```

### Bash

1. **Open the configuration file:**

```bash
nano ~/.bashrc
```

> **Note:** If you're using Bash on macOS, edit `~/.bash_profile` instead.

2. **Add the following line at the top of the file:**

```bash
export PATH="$HOME/.local/bin:$PATH"
```

3. **Save and exit:** `Ctrl + O` → `Enter` → `Ctrl + X`
4. **Apply the configuration:**

```bash
source ~/.bashrc
```

5. **Verify installation:**

```bash
orbitron --version
```

### Fish

1. **Open the configuration file:**

```bash
nano ~/.config/fish/config.fish
```

2. **Add the following line:**

```fish
fish_add_path $HOME/.local/bin
```

3. **Save and exit:** `Ctrl + O` → `Enter` → `Ctrl + X`
4. **Open a new terminal** (recommended) or run:

```fish
source $HOME/.config/fish/config.fish
```

5. **Verify installation:**

```bash
orbitron --version
```

### Sh / Ash (Alpine Linux, etc.)

1. **Open the configuration file:**

```bash
nano ~/.profile
```

2. **Add the following line:**

```bash
export PATH="$HOME/.local/bin:$PATH"
```

3. **Save and exit:** `Ctrl + O` → `Enter` → `Ctrl + X`
4. **Apply the configuration:**

```bash
. ~/.profile
```

5. **Verify installation:**

```bash
orbitron --version
```

***

## Windows

### Method 1: Add PATH via System Settings (Recommended)

1. Press `Win + R` to open the Run dialog
2. Type `sysdm.cpl` and press `Enter`
3. Click the **Advanced** tab → **Environment Variables**
4. Under **User variables**, select `Path` → Click **Edit**
5. Click **New** and add the following path:

```
%USERPROFILE%\.local\bin
```

6. Click **OK** to close all windows
7. Open a new PowerShell or Command Prompt window
8. **Verify installation:**

```powershell
orbitron --version
```

### Method 2: Edit PowerShell Profile

1. **Open the profile file in PowerShell:**

```powershell
notepad $PROFILE
```

> **Note:** If you get an error that the file doesn't exist, create it first:
>
> ```powershell
> New-Item -Path $PROFILE -ItemType File -Force
> notepad $PROFILE
> ```

2. **Add the following line in Notepad:**

```powershell
$env:Path = "$env:USERPROFILE\.local\bin;" + $env:Path
```

> **Note:** Using the `$env:USERPROFILE` environment variable ensures it works even if the username changes.

3. **Save** (`Ctrl + S`) and close Notepad
4. **Reload the profile:**

```powershell
. $PROFILE
```

5. **Verify installation:**

```powershell
orbitron --version
```

### Method 3: Permanent Registration via PowerShell Command

Add PATH for the current user only without administrator privileges:

```powershell
$binPath = "$env:USERPROFILE\.local\bin"
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($currentPath -notlike "*$binPath*") {
    [Environment]::SetEnvironmentVariable("Path", "$binPath;$currentPath", "User")
    Write-Host "PATH has been added. Please open a new terminal."
}
```

***

## Verification Methods

### Check if PATH is Registered

**macOS / Linux:**

```bash
echo $PATH | tr ':' '\n' | grep '.local/bin'
```

The output should include `/Users/username/.local/bin` or `/home/username/.local/bin`.

> **Note:** Using just `grep local` may also match `/usr/local/bin`, etc.

**Windows (PowerShell):**

```powershell
$env:Path -split ';' | Where-Object { $_ -like '*\.local\bin*' }
```

### Check Orbitron Executable Path

**macOS / Linux:**

```bash
which orbitron
```

Expected output: `/Users/username/.local/bin/orbitron`

**Windows (PowerShell):**

```powershell
Get-Command orbitron | Select-Object Source
```

Expected output: `C:\Users\username\.local\bin\orbitron.exe`

***

## Troubleshooting

### "command not found" Error Persists

1. **Make sure you opened a new terminal**
   * Instead of using the `source` command, completely close and reopen your terminal
2. **Check PATH order**
   * `~/.local/bin` should be at the beginning of your PATH
   * If an older version exists in another path, it may run first
3. **Verify you edited the correct configuration file**
   * Check your current shell: `echo $SHELL` (macOS/Linux)
   * Make sure you edited the configuration file for that shell

### Older Version Keeps Running

Remove the previous installation:

**Unix/Linux/macOS:**

```bash
# Remove only the legacy binary (safe)
rm ~/.orbitron/bin/orbitron

# Clean up empty directories (optional)
rmdir ~/.orbitron/bin 2>/dev/null
rmdir ~/.orbitron 2>/dev/null

# Or remove the entire legacy directory (includes settings - use with caution)
rm -rf ~/.orbitron

# Restart shell
exec $SHELL
```

**Windows:**

```powershell
# Remove only the legacy binary (safe)
Remove-Item "$env:USERPROFILE\.orbitron\bin\orbitron.exe"

# Or remove the entire legacy directory (includes settings - use with caution)
Remove-Item -Recurse -Force "$env:USERPROFILE\.orbitron"
```

For more troubleshooting help, see the [Troubleshooting](/orbitron-docs/user-guide/installation/troubleshooting.md) page.

***

## Related Documentation

* [Installation Guide](/orbitron-docs/user-guide/installation.md) - How to install Orbitron
* [Troubleshooting](/orbitron-docs/user-guide/installation/troubleshooting.md) - Solving installation issues
* [Migration Guide](/orbitron-docs/user-guide/installation/migration-guide.md) - Upgrading from legacy versions