Skip to main content

Installing Atomic

This guide will help you install Atomic VCS on your system. The recommended installation path is the hosted installer script from Atomic Storage. Development builds can still be installed from source.

Installation Methods​

Install the latest Atomic CLI release with the installer hosted by Atomic Storage:

curl -sSf https://atomic.storage/install.sh | sh

Install a specific version:

curl -sSf https://atomic.storage/install.sh | ATOMIC_VERSION=0.5.1 sh

Install to a user-writable directory:

curl -sSf https://atomic.storage/install.sh | ATOMIC_INSTALL="$HOME/.local/bin" sh

The installer detects your platform, downloads the matching GitHub release archive, verifies checksums when available, and installs the atomic binary.

Verify Installation​

atomic --version

Source Install (Development)​

Use a source install when you need to test unreleased changes.

1. Install Rust​

If you don't have Rust installed, download and install rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Choose the stable toolchain as your default:

rustup default stable

If you already have rustup installed, make sure to update it:

rustup update

2. Install System Dependencies​

Install the required libraries and header files for your operating system:

On Debian/Ubuntu:

sudo apt update
sudo apt install make libsodium-dev libclang-dev pkg-config \
                 libssl-dev libxxhash-dev libzstd-dev clang

On macOS:

brew install llvm libsodium openssl xxhash zstd

On Arch Linux:

sudo pacman -S clang libsodium gcc-libs rustup pkgconf \
               diffutils make xxhash zstd

On openSUSE Tumbleweed:

sudo zypper in clang-devel libopenssl-devel libsodium-devel \
               libzstd-devel pkgconfig xxhash-devel

On Fedora:

sudo dnf install clang-devel openssl-devel libsodium-devel \
                 libzstd-devel pkgconfig xxhash-devel

On Void Linux:

sudo xbps-install libgcc-devel libressl-devel libsodium-devel \
                  libzstd-devel xxHash-devel

3. Build and Install Atomic​

Clone the repository and install the CLI crate:

git clone https://github.com/atomicdotdev/atomic.git
cd atomic
cargo install --path atomic-cli

4. Add to PATH (if needed)​

If the atomic command is not found, you may need to add Cargo's bin directory or your chosen installer directory to your PATH.

On Linux/macOS, add to your ~/.bashrc, ~/.zshrc, or equivalent:

export PATH="$PATH:$HOME/.cargo/bin"

On Linux with systemd, you can also add to ~/.config/environment.d/envvars.conf:

PATH=$PATH:$HOME/.cargo/bin

Then reload your shell configuration:

source ~/.bashrc  # or source ~/.zshrc

Distribution Packages​

COMING SOON

Building from Git (Development)​

To build the latest development version:

git clone https://github.com/atomicdotdev/atomic.git
cd atomic
cargo build --release --all-features
cargo test
cargo install --path atomic-cli

Troubleshooting​

"Package not found" errors​

Make sure you've installed all required system dependencies for your platform. The build process requires development headers for several libraries.

Linker errors on macOS​

If you encounter linker errors on macOS, ensure you have the Xcode Command Line Tools installed:

xcode-select --install

You may also need to set the following environment variables:

export LIBRARY_PATH="$LIBRARY_PATH:$(brew --prefix)/lib"
export CPATH="$CPATH:$(brew --prefix)/include"

Permission denied errors​

If you get permission errors during installation, ensure your user has write access to the Cargo installation directory, or use sudo (not recommended) or install to a user-writable location.

Rust version too old​

Atomic requires Rust 1.70 or later. Update your Rust installation:

rustup update stable

Next Steps​

Now that you have Atomic installed, you're ready to:

  1. Follow the Quickstart to register with Atomic Storage and push a hosted project
  2. Create your first local repository
  3. Learn the team collaboration model
  4. Explore the command reference

Uninstalling​

To remove Atomic installed by the hosted installer:

rm /usr/local/bin/atomic

If you installed to a custom ATOMIC_INSTALL directory, remove the binary from that directory instead.

To remove Atomic installed via Cargo:

cargo uninstall atomic-cli

Need help? open an issue on GitHub.