Skip to content

Installation

This guide uses uv, a fast Python package manager that handles Python installation automatically. If you prefer traditional tools, see the pip installation guide.

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Other installation methods
  • macOS with Homebrew: brew install uv
  • Windows with winget: winget install --id=astral-sh.uv -e

See the uv installation docs for more options.

After installation, you may need to restart your terminal or run source ~/.bashrc (Linux) / source ~/.zshrc (macOS) for the uv command to be available.

2. Create a project

Run the following command to create a new uproot project:

uv run --with 'uproot-science[dev] @ git+https://github.com/mrpg/uproot.git@main' uproot setup my_project

This command:

  1. Downloads and installs the latest version of uproot
  2. Creates a new directory called my_project
  3. Generates starter files including a sample experiment

You should see output like this:

📂 A new project has been created in 'my_project'.
✅ 'main.py' and some other files have been written.
🚶 Go to the new project directory by running
    cd my_project
📖 Get started by reading 'main.py'.
🚀 Then you may run this project using
    uv run uproot run

3. Run uproot

Navigate to your new project and run the command shown in the output above:

cd my_project
uv run uproot run

The first run will set up a virtual environment and install dependencies automatically. You'll see:

INFO:     Started server process [...]
INFO:     Waiting for application startup.
INFO:uproot:This is uproot 0.0.1 (https://uproot.science/)
INFO:uproot:Server is running at http://127.0.0.1:8000/

4. Access the admin interface

Open your browser and go to http://127.0.0.1:8000/admin/.

The server output includes an auto-login URL that looks like:

Auto login:
     http://127.0.0.1:8000/admin/login/#aBcDeFgHiJkL...

Click this URL or copy it to your browser to log in automatically. This auto-login feature only appears when using the default administrator with an empty password.

What's next?

Now that uproot is running, you can:

Troubleshooting

uv command not found

If you get "command not found" after installing uv:

  1. Close and reopen your terminal
  2. Or run source ~/.bashrc (Linux) / source ~/.zshrc (macOS)
  3. Or add ~/.local/bin to your PATH manually

Permission errors on Linux

If you encounter permission errors, make sure you're not running as root. uv is designed to work in user space.

Port already in use

If port 8000 is already in use, you can specify a different port:

uv run uproot run --port 8001

Getting help