Documentation · Project overview
linux-setup installs a repeatable Linux terminal configuration and a pinned set
of command-line tools. It links configuration to this checkout, so keep the
checkout in a persistent location.
Ubuntu/Debian on x86_64 is the primary target; development testing used Ubuntu 26.04 x86_64. ARM64 release mappings are included but still need equivalent hardware validation. Ubuntu/Debian inside WSL uses the same Linux installation path. Other glibc distributions need their own base packages installed first and are not yet integration-tested. Native Windows/PowerShell, macOS, and musl Linux are outside this release's supported targets.
Pinned binaries still depend on compatible host libraries. Pinning tools does not freeze the operating system or guarantee compatibility with every older distribution release.
Required bootstrap components are Bash, Python 3.9 or newer, a working HTTPS
connection, and trusted certificate authorities. Git is needed to clone the
repository; a downloaded ZIP is another way to obtain the files. On Ubuntu/Debian,
rootless base-tool installation also requires apt-get, dpkg-deb, and populated
package indexes.
git clone https://github.com/zdevzone/linux-setup.git ~/linux-setup
cd ~/linux-setup
./install.sh --preflight
./install.sh --dry-run
./install.sh
export PATH="$HOME/.local/bin:$PATH"
exec zsh
linux-doctorThe preflight checks prerequisites before installation. Its GitHub homepage probe
is advisory: a failure may not reflect access to release downloads, which are
checked during installation. If installation fails, do not run exec zsh until
the error has been resolved and installation succeeds. The dry run describes the
installation without applying it. Downloaded artifacts are verified against the
SHA-256 values in tools.lock.json; repeat installs reuse verified downloads.
If Ubuntu/Debian bootstrap prerequisites or current package indexes are missing:
./install.sh --install-prerequisitesThis explicit option displays the administrative package operations before
requesting authentication. It prepares Python, Git, curl, certificate trust, and
APT indexes, then continues the normal installation. To preview both stages, add
--dry-run; --yes explicitly confirms the administrative prerequisite commands
for automation. Normal tool installation does not need sudo: missing base programs
are extracted into your user directory. On restricted devices, ask the system
administrator to provide prerequisites instead.
On other compatible glibc Linux distributions, install Bash, Python 3.9+, Git,
curl, CA certificates, Zsh, tmux, file, lsof, and the PostgreSQL client (psql)
through the distribution's package manager before running this installer.
Do not run the entire installer with sudo; it is intended to configure the
current user's home directory.
The README tool table lists the included programs. Already available base programs are reused. Existing Vite+ and uv installations are preserved. Fresh Vite+/uv installations use the lockfile versions.
Zsh is installed automatically when it is missing during a normal ./install.sh
run on Ubuntu/Debian. Its packages and runtime files stay in your user directory,
with an executable entry point at ~/.local/bin/zsh; no sudo or login-shell change
is needed. An existing Zsh is reused. --config-only deliberately skips all tool
installation, including Zsh. At completion, the installer prints an exec command
with the full Zsh path so it also works before your current shell has added
~/.local/bin to PATH.
On an interactive normal installation, the installer asks for a Git author name
and email only when the corresponding global value is missing. It then offers
GitHub CLI installation and account setup on the first interactive run. Existing
values and an existing gh installation are preserved. Non-interactive runs,
preflight, dry runs, and configuration-only runs do not prompt. You can revisit
the account flow with ./install.sh --github-setup, or install just the optional
CLI with ./install.sh --install-gh. The GitHub CLI download is pinned and
checksum-verified like the other managed tools.
The first interactive installation also offers the optional AI skill manager.
Choose Codex or Claude Code, an area of work, and global or project scope. You
can skip this step and run skill-manager later. See
AI skills for sources and removal.
The PostgreSQL dependency is the psql client only. Installing it does not create
a database cluster or start a server. Your applications retain responsibility for
their Node/Python versions and dependency lockfiles.
The ownership manifest records managed programs, configuration links, backups, and integrations so the uninstaller can separate setup-owned resources from pre-existing installations.
Default locations, respecting the corresponding XDG variables:
| Content | Default location |
|---|---|
| Configuration checkout link | ~/.config/linux-setup |
| Private machine additions | ~/.config/linux-setup-local/ |
| Executable entry points | ~/.local/bin/ |
| Managed programs and plugins | ~/.local/share/linux-setup/ |
| Downloads and setup caches | ~/.cache/linux-setup/ |
| Manifest, backups, recovery records | ~/.local/state/linux-setup/ |
| Zsh history | ~/.local/state/zsh/history |
The installer backs up configurations it replaces. The Git include applies this
project's diff settings without copying your Git identity into the repository.
If Codex is present and the oh-my-posh MCP registration is absent, the normal
install adds the endpoint. An existing registration is preserved. Use --skip-mcp
to leave that integration alone.
Run the current installer from the renamed or freshly cloned linux-setup
checkout. It recognizes the earlier dev-setup directories and manifest,
preserves original backups and personal additions, and updates managed paths.
Compatibility paths may remain so older wrappers and customizations continue to
resolve. Do not delete those paths by hand while retained tools still use them.
LINUX_SETUP_DIR is the canonical environment variable; DEV_SETUP_DIR remains
available for existing scripts. The familiar dev-doctor, devsetup, dev-db,
and dev-ports commands remain usable. New branding also provides linux-doctor
and linuxsetup.
Migration is repeatable after interruption. If both old and new locations contain different data, the installer reports the conflict instead of overwriting it. Resolve the reported paths and rerun; never remove backups or recovery records just to clear a conflict. Earlier manifests have incomplete program ownership, so uninstallation keeps uncertain resources and reports them for review.
To move a checkout later, move/copy it to its persistent destination and rerun
./install.sh there to repair managed links. Open a new shell afterward.
Installing Zsh and setting the account's login shell are separate operations. Inspect the installed executable first:
command -v zshUse that absolute path. If it is missing from /etc/shells, an administrator must
register it. Then run chsh -s /absolute/path/to/zsh and authenticate when asked.
Log out and back in for the account change to take effect.
If you choose the managed ~/.local/bin/zsh, removing it later requires switching
the account to another registered shell first. The uninstaller checks this.
Choose a Nerd Font in the terminal emulator that renders your session. With WSL
or SSH, that is normally the Windows/desktop client, not the remote Linux host.
One font installation option on a local desktop is
oh-my-posh font install meslo; select it in the terminal settings afterward.
Extra Yazi previews use optional tools:
sudo apt install ffmpeg poppler-utils 7zipThese provide video, PDF, and archive previews. Packages installed manually with this command belong to the system package manager; the setup uninstaller does not claim or remove them. Basic file navigation, search, JSON previews, and fuzzy selection use the tools already included in the setup.
For download errors, missing libraries, or completion problems, see troubleshooting.