Install Script¶

Reference documentation for the install.py installation script.

Overview¶

The install.py script automates the complete setup process for the Neovim configuration on macOS and Linux.

Running the Script¶

Basic usage:

python3 install.py

The script is interactive - you’ll be prompted for each step:

Neovim v0.11.4 Setup
==================================================

Create necessary directories? (y/n): y
✓ Created /Users/username/.config/nvim
...

Continue with next step? (y/n): y
...

What it installs:

Neovim v0.11.4
Python virtual environment with required packages
JetBrains Mono Nerd Font
Configuration symlinks
Treesitter language parsers
Optional: Rust tools (Linux only)

Installation Steps¶

Step 1: Create Directories

Creates necessary directories:

~/.config/nvim - Neovim configuration
~/.virtualenvs - Python virtual environments
~/.dotfiles/nvim - Configuration location (if needed)
~/.local/bin - User binaries

Step 2: Install Neovim

macOS:

Checks for Homebrew
If installed: Uses brew install neovim
If not installed: Downloads binary from GitHub
Extracts and sets up binary

Linux:

Downloads AppImage
Makes executable
Sets up in ~/.apps/neovim/

Step 3: Setup Python Virtual Environment

Creates isolated Python environment:

Creates ~/.virtualenvs/nvim/
Installs uv (fast Python package manager)
Creates virtual environment
Verifies creation

Step 4: Clone Configuration

Clones the Neovim configuration:

git clone https://github.com/clintonsteiner/nvim.git ~/dotfiles/nvim

If directory exists, asks whether to use existing or replace.

Step 5: Install Python Packages

Installs into the virtual environment:

pynvim
zuban
ruff
darker

Uses uv pip install for speed.

Step 6: Install Nerd Font

Installs JetBrains Mono Nerd Font for icon rendering:

macOS: Uses Homebrew cask (font-jetbrains-mono-nerd-font) when available
Linux: Downloads and extracts to ~/.local/share/fonts/NerdFonts/JetBrainsMono
Refreshes font cache on Linux when fc-cache is available

After install, set your terminal font to JetBrains Mono Nerd Font.

Step 7: Create Symlinks

Links configuration to Neovim config directory:

ln -s ~/dotfiles/nvim/init.lua ~/.config/nvim/init.lua
ln -s ~/dotfiles/nvim/lua ~/.config/nvim/lua

Step 8: Create Launch Script

Creates ~/.local/bin/nvim for easy launching.

Step 9: Install Treesitter

Installs syntax highlighting parsers:

python
lua
comment
vim
vimdoc
c
sql
query

Step 10: Install Rust Tools (Linux only)

Optionally installs:

eza (modern ls replacement)
fd (fast find)
ctags (code navigation)

Customizing the Script¶

Edit the script:

vim install.py

Common modifications:

Change Neovim version:

self.neovim_version = "0.12.0"  # Change from 0.11.4

Change installation paths:

self.neovim_dir = self.home / "my_apps" / "neovim"

Skip certain steps:

Comment out in the run() method:

steps = [
    ("Creating directories", self.create_directories),
    # ("Downloading Neovim", self.download_neovim),  # Skip this
    # ...
]

Change Python packages:

Edit pyproject.toml:

[project]
dependencies = [
    "pynvim>=0.4.3",
    "my-package>=1.0.0",  # Add custom package
]

Script Structure¶

Class: NvimSetup

Main class handling all setup operations.

Key methods:

__init__ - Initialize paths and load dependencies
run - Main entry point
create_directories - Create needed folders
download_neovim - Install Neovim
setup_venv - Create Python environment
clone_config - Clone this configuration
install_python_packages - Install dependencies
install_nerd_font - Install JetBrains Mono Nerd Font
create_symlinks - Link config files
create_launch_script - Create launcher
install_treesitter - Install language parsers
install_cargo_tools - Install Rust tools

Helper methods:

run_command - Execute shell commands safely
confirm - Ask user for confirmation
_load_dependencies - Read pyproject.toml

Error Handling¶

The script handles errors gracefully:

try:
    subprocess.run(cmd, check=True, capture_output=False)
    return True
except subprocess.CalledProcessError as e:
    print(f"✗ Failed to {description}: {e}")
    return False

Common error messages:

✗ Failed to install Neovim: [error details]
✗ Command not found: brew
✗ Permission denied: /path/to/directory

```

If a step fails:

The script continues (doesn’t abort)
Failed steps are tracked
Summary shows which steps failed
You can fix issues and run again

Automation¶

Run without prompts:

The script requires user confirmation for each step. To automate (use with caution):

Create a wrapper script:

#!/bin/bash
(
    echo y
    echo y
    echo y
    # ... more y's for each prompt
) | python3 install.py

Or modify install.py:

# In install.py, replace:
if not self.confirm("Create necessary directories?"):
    return False

# With:
# Automatically proceed

```

Running on CI/CD¶

The script can run in CI environments:

# GitHub Actions example
- name: Setup Neovim
  run: |
    python3 install.py << EOF
    y
    y
    y
    y
    y
    y
    y
    y
    n
    EOF

Check Exit Code¶

The script returns exit codes:

python3 install.py
echo $?  # 0 = success, 1 = failure

Use in scripts:

python3 install.py
if [ $? -ne 0 ]; then
    echo "Installation failed"
    exit 1
fi

Dependencies¶

Required:

Python 3.8+
Git
curl
tar (for extraction)

Optional:

Homebrew (macOS, for easy Neovim installation)
cargo (for Rust tools on Linux)

The script checks for these and provides helpful error messages if missing.

Troubleshooting the Installer¶

Error: File not found

FileNotFoundError: [Errno 2] No such file or directory: 'python3 install.py'

Solution: Run from the correct directory:

cd ~/dotfiles/nvim
python3 install.py

Error: Permission denied

PermissionError: [Errno 13] Permission denied: '/Users/username/.config/nvim'

Solution: Fix permissions:

chmod -R 755 ~/.config/nvim

Error: Curl/Git not found

Solution: Install missing tools:

brew install git  # macOS
sudo apt-get install git  # Linux

Error: Virtual environment creation fails

Solution: Ensure Python is working:

python3 --version
python3 -m venv ~/.virtualenvs/test-nvim

Error: Treesitter installation hangs

Solution: The installation takes time (minutes). Be patient.

If it truly hangs, cancel with Ctrl+C and check:

nvim -c "TSInstall python lua comment vim vimdoc c sql query" -c "quit"

Manual Installation Alternative¶

If the script fails, you can install manually. See Installation for step-by-step instructions.

Modifying the Script¶

Add new installation step:

def install_custom_tool(self) -> bool:
    """Install a custom tool."""
    if not self.confirm("Install custom tool?"):
        return False

    if not self.run_command(
        ["curl", "-o", "/tmp/mytool", "https://example.com/mytool"],
        "download custom tool"
    ):
        return False

    print("✓ Installed custom tool")
    return True

Then add to steps in run():

steps = [
    # ... existing steps ...
    ("Installing custom tool", self.install_custom_tool),
]

Change confirmation message:

# Edit the confirm() call
if not self.confirm("Install Neovim v{} (macOS only)?".format(self.neovim_version)):
    return False

Distributing Modified Versions¶

If you customize the script:

Keep it in your fork
Document changes in README
Share with others who want same setup

Example: Creating company-specific setup:

# Fork the repo
git clone https://github.com/yourcompany/nvim-config.git

# Modify install.py for company standards
vim install.py

# Commit and push
git add install.py
git commit -m "Company-specific setup"
git push

Developers can then run:

git clone https://github.com/yourcompany/nvim-config.git
cd nvim-config
python3 install.py

Next Steps After Installation¶

After running the script:

Verify installation:
```
nvim
:checkhealth
```
Review configuration:
```
cat ~/.config/nvim/init.lua
```
Customize as needed:

See Customization for how to modify.
Add to PATH (if needed):
```
export PATH=$HOME/.local/bin:$PATH
```

Commit your customizations:

cd ~/dotfiles/nvim
git add .
git commit -m "My customizations"

Getting Help¶

If the installer fails:

Note the error message
Check Troubleshooting
Check :checkhealth in Neovim
Try manual installation (Installation)
Report issue with error details

Source Code¶

The complete script is in install.py - it’s readable and well-commented.

You can:

Read it to understand what it does
Modify it for your needs
Reference it in your own scripts
Learn from it

The script is approximately 450 lines of well-structured Python.