1Panel Upgrade

1Panel is an open-source server management panel for Linux, built on Docker and designed to simplify website hosting, da

1Panel is an open-source server management panel for Linux, built on Docker and designed to simplify website hosting, database administration, scheduled tasks, and application deployment. Because the project releases updates frequently, keeping the panel current is essential for receiving security patches, performance improvements, and new features.

A routine upgrade is generally straightforward, but it still involves a brief panel restart and changes to core panel files. Preparing the server in advance and validating the system afterward can prevent an otherwise routine maintenance task from becoming an incident.
Complete the following checks before upgrading:

Back up the panel. In most installations, panel data is stored under /opt/1panel. Use the backup feature under Panel Settings → Backup to create a snapshot, or archive the directory manually.
Review the release notes. Check the official GitHub Releases page for the target version. Pay particular attention to breaking changes, migration requirements, and changes involving Docker, databases, or panel configuration.
Verify the host environment. Make sure the server has a stable network connection, Docker is running, and there is enough free disk space for the new version and temporary installation files.
Choose a low-traffic window. The panel may be unavailable for a short period while it restarts. Avoid peak business hours, especially when other administrators depend on the panel.
Confirm access options. Keep an SSH session available in case the web interface becomes temporarily inaccessible during the upgrade.

Updating Through the Web Interface

The web interface is the most convenient option for most administrators.

Sign in to the 1Panel dashboard.
Navigate to Panel Settings → About.
Select Check for Updates.
Review the available version and click Update.
Confirm the operation in the dialog and wait for the installation to finish.
Refresh the page and sign in again if necessary.

The panel downloads the required files, replaces the existing application files, and restarts its services automatically. The process often takes only a few minutes, although the exact duration depends on the server connection and package size.

Updating from the Command Line

The built-in 1pctl utility provides a reliable alternative when you prefer SSH or cannot access the web interface.

Run:

1pctl update

The command retrieves the latest available release and installs it automatically. Once the update completes, confirm the installed version with:

1pctl version

The utility can also help with common administration tasks. For example:

1pctl user-info

This displays information about the panel entry point and administrator account. Administrators can also use commands such as the following to adjust the panel port:

1pctl update port

Command-line access is especially useful for automated maintenance, remote servers with restricted browser access, and troubleshooting situations where the panel UI does not load correctly.

Performing an Offline Upgrade

Servers without direct internet access can be upgraded with an offline package.

First, download the appropriate release package from the official 1Panel GitHub repository on a machine that has internet connectivity. Select a package that matches the target server’s CPU architecture and operating system.

Then transfer the package to the restricted server and open Panel Settings → About in 1Panel. Select the offline upgrade option, upload the package, and confirm the installation.

Before transferring large files, verify the package name and checksum if the release page provides them. An incomplete or mismatched package may fail during installation.

Verifying the Upgrade

Do not treat a completed progress indicator as sufficient proof of success. Perform a short post-upgrade check:

Open Panel Settings → About and confirm that the displayed version matches the intended release.
Inspect running containers:
```
docker ps
```
Confirm that panel-related services and important workloads, such as websites and databases, remain healthy.
Test several applications or websites to ensure that they respond as expected.
Review the panel logs stored by default under:
```
/opt/1panel/log
```
Look for repeated errors, failed service starts, permission problems, or database connection failures.
Check basic administrative functions, including creating a test task or reviewing application status.

If your environment monitors services or websites externally, run those checks as well. They can reveal issues that are not visible from inside the panel.

Common Concerns and Troubleshooting

Will running applications be interrupted?

A normal 1Panel upgrade replaces the panel application rather than the containers that power your websites and databases. As a result, business workloads usually continue running without interruption. The panel itself may restart, and unusual configurations should still be tested before maintenance begins.

What should I do if the upgrade fails?

Start by reviewing the installation output and relevant logs. Common causes include:

Network timeouts or blocked access to the update server
Insufficient disk space
Incorrect offline package architecture
Permission issues in the installation directory
An active Docker or container service that prevents file replacement

Resolve the underlying issue and run the update again. Avoid repeatedly restarting the upgrade while a previous installation process is still active, as concurrent operations may leave the panel in an inconsistent state.

Can I move directly to a major release?

Major-version transitions may require additional migration steps. Read the official release notes and migration documentation before proceeding, and create a complete backup that includes both panel data and any critical application data. Test the upgrade on a staging system when possible.

Can I downgrade after an unsuccessful update?

Downgrades are not generally recommended. A newer release may modify configuration or data structures in ways that an older version cannot safely interpret. If rollback is unavoidable, use the installation package or script for the exact earlier version and restore the relevant backup. Do not replace only the panel executable while leaving newer configuration or data files in place.

Regular upgrades help keep 1Panel secure and compatible with the latest platform improvements. For most installations, the web interface is the fastest and simplest choice, while 1pctl offers a dependable fallback. Regardless of the method, the safest pattern is always the same: prepare a backup, review the release notes, schedule a suitable maintenance window, and verify the system after the update.