Extract
Extract archives from the Nextcloud web interface. Pick an archive in the Files app, choose Extract here, and the app unpacks it into a new folder next to the archive.
โจ Features
- ๐๏ธ Extract in place from the Files app file action, no shell access needed
- ๐๏ธ Multiple formats: Zip, Rar, Tar, Tar.gz, Tar.bz2, Gzip, 7z and Deb
- ๐ Works with external storage, including group folders
- ๐ Respects Nextcloud file permissions and removes blacklisted file names
- ๐งน Cleans up a temporary directory left behind by an interrupted run
- ๐ Capabilities API so clients can discover the supported archive types
- ๐ Translated through the Nextcloud translation pipeline
- ๐งช Unit tested and compatible with Nextcloud 33-35
๐ Requirements
| Component | Version |
|---|---|
| Nextcloud | 33-35 |
| PHP | 8.1+ |
| Node.js | 24+ (development only) |
| npm | 10.5+ (development only) |
Archive tooling
| Tool | Purpose | Install |
|---|---|---|
PHP zip extension | Zip archives | bundled with most PHP builds |
PHP rar extension or unrar | Rar archives | pecl install rar or apt-get install unrar |
p7zip / p7zip-full | Tar, Gzip, Bzip2, 7z, Deb | apt-get install p7zip p7zip-full |
The zip PHP extension is required for Zip files. Rar needs either the PHP
rar extension or the unrar binary; every other format is handled by the
7za binary shipped with p7zip.
Ubuntu / Debian
sudo apt-get install p7zip p7zip-full unrarFedora / RHEL / CentOS
sudo dnf install p7zip p7zip-plugins unrarmacOS
brew install p7zip๐ฆ Installation
Note: Extract is not listed in the Nextcloud App Store. Install it from a release archive or from source as described below.
From a release archive (recommended)
- Download the latest
extract.tar.gz(orextract.zip) from the releases page. - Extract it into your Nextcloud
appsdirectory, using the command that matches the archive you downloaded:The archive already contains the built frontend assets, so no Node.js step is needed.# If you downloaded extract.tar.gz: tar -xzf extract.tar.gz -C /path/to/nextcloud/apps # If you downloaded extract.zip: unzip extract.zip -d /path/to/nextcloud/apps chown -R www-data:www-data /path/to/nextcloud/apps/extract - Enable the app:
occ app:enable extract
From source
-
Clone the repository into your Nextcloud
appsdirectory:cd /path/to/nextcloud/apps git clone https://github.com/ashcoft/extract.git extract -
Set the permissions:
chown -R www-data:www-data extract -
Install the PHP and frontend dependencies and build the assets:
cd extract composer install npm ci npm run build -
Enable the app:
occ app:enable extractOr go to Settings โ Apps, find "Extract" in the disabled apps section and click Enable.
๐ Usage
- Open the Files app and navigate to an archive.
- Right-click the archive and choose Extract here.
- The app unpacks the archive into a new folder named after the archive, in the same directory.
The action is only offered when you have permission to change the file, and only for archives whose MIME type the app can extract.
Supported formats
| Format | Extensions | Extraction backend |
|---|---|---|
| Zip | .zip | PHP zip extension |
| Rar | .rar | PHP rar extension or unrar |
| Tar | .tar | 7za |
| Tar + Gzip | .tar.gz, .tgz | 7za |
| Tar + Bzip2 | .tar.bz2, .tbz2 | 7za |
| Gzip | .gz | 7za |
| 7z | .7z | 7za |
| Deb | .deb | 7za |
Note: Archives protected by a password are not supported. Extraction works on a normal Nextcloud data directory, on object storage and with server-side encryption enabled. On non-local storage the archive is unpacked into a temporary directory and the result is imported through the Nextcloud filesystem, so it appears in the Files app like any other folder.
External storage
Archives on an external storage are unpacked through a temporary folder in the app's own data directory, then moved into place. If a previous run was interrupted, that temporary folder is removed before the new extraction starts.
๐ ๏ธ Development
Prerequisites
- Node.js 24+
- npm 10.5+
- PHP 8.1+ with the
zipextension - Nextcloud 33-35 development environment
Setup
git clone https://github.com/ashcoft/extract.git
cd extract
composer install
npm ciBuild commands
npm run dev # development build
npm run build # production build
npm run watch # rebuild on change
npm run lint # ESLint
npm run lint:fix # ESLint with autofix
npm run stylelint # Stylelint
npm run typescript:check # tsc --noEmit
npm run typescript:generate # regenerate OpenAPI types from openapi.jsonThe Makefile wraps the common flows:
make dev-setup # clean, install and build the production bundle
make production-setup # same as dev-setup
make appstore # build the installable extract.tar.gz and extract.zip
make test # run the PHPUnit suite and the frontend linter
make lint # run the PHP and frontend linters
make dist # build the source package and the app-store archivesmake appstore stages only the runtime files, then writes
build/artifacts/extract.tar.gz and, when zip is installed,
build/artifacts/extract.zip. Without zip it skips the zip with a warning;
the release workflow installs zip so both archives are always attached.
It packages whatever is already in js/ and css/, and it does not build the
frontend itself, so run make build first on a fresh checkout. make dist is
not a substitute: it only runs the source and app-store targets.
๐งช Testing
Run the PHPUnit suite:
composer run test:unit # phpunit -c tests/phpunit.xmlStatic analysis and linting:
composer run lint # php -l over every PHP file
composer run cs:check # php-cs-fixer --dry-run
composer run psalm # Psalm
npm run lint # ESLint
npm run typescript:check # TypeScriptThe PHPUnit suite covers the extraction service, the capabilities endpoint and the mapping between Nextcloud's archive MIME types and the extraction strategy.
๐ข Releases
Releases are automated. On every push to main the Release workflow:
- runs semantic-release to decide the next version from the commit messages,
- bumps
appinfo/info.xmlandpackage.json, commits the change and creates the tag, - builds
extract.tar.gzandextract.zipfrom the tagged commit, - uploads both archives to the GitHub release and publishes it.
Because the version comes from the tags, appinfo/info.xml must never be ahead
of the latest tag. If it is, the workflow stops and tells you to tag the current
commit so the next release continues from the declared version.
๐ Troubleshooting
The "Extract here" action is missing
- Confirm the Extract app is enabled in Settings โ Apps.
- Check that the file is one of the supported formats.
- Make sure you have permission to change the file; the action needs update rights.
- Review the Nextcloud log at
data/nextcloud.log.
"Oops something went wrong."
The archive tool could not unpack the file. Common causes:
- Tool missing: for Rar archives install the PHP
rarextension or theunrarbinary; for every other format installp7zipandp7zip-fulland check that7zais on thePATHof the web server user. - Damaged or unreadable archive: the file is truncated, corrupt, or not actually an archive of that format.
- Permissions: the web server user cannot read the archive or write into the target folder.
- Insufficient space on the volume holding the archive.
For a failed 7za or unrar run the Nextcloud log records the exit code and the
tool output. Zip extraction and a missing tool are not logged with that detail.
"Unsupported archive type"
The file's MIME type is not one the app can extract. See supported formats for the list.
Extraction on object storage or with server-side encryption
This works. Nextcloud cannot hand out a path inside the data directory there, so the archive is unpacked into a temporary directory and the result is imported through the Nextcloud filesystem. The extracted folder then appears in the Files app like any other folder.
- Object storage (S3, Swift, โฆ).
getLocalFile()returns a temporary copy rather than a file in the data directory. - Server-side encryption enabled. The encryption storage wrapper does the same, because it has to decrypt to a temporary file first.
The app detects both through Storage::isLocal(). On local storage it keeps
unpacking the archive next to the original file, which avoids copying the
payload a second time.
If extraction used to report "Extraction is only supported on local storage" on these setups, update to a version that includes the import step.
A password-protected archive
Password-protected archives are not supported. Zip and the 7-Zip formats report
"Oops something went wrong."; Rar with the PHP rar extension is the exception,
because that path does not surface a failure.
Large archives
Extraction happens on the server, so give the PHP process enough memory and
time. Very large archives may need a higher memory_limit and
max_execution_time.
๐ค Contributing
Contributions are welcome.
- Fork the repository.
- Create a branch for your change.
- Make your change and add or update tests.
- Run the checks:
composer run test:unit && composer run lint && npm run lint. - Commit with a conventional commit
message, for example
fix: handle empty archives. - Push the branch and open a Pull Request.
The commit type drives the release:
| Commit | Release |
|---|---|
breaking change (feat!, BREAKING CHANGE) | major |
feat | minor |
perf | minor |
fix(deps) | minor |
fix (any other scope) | patch |
chore, docs, test, ci, refactor, style, build, revert | none |
So a dependency fix bumps the minor version, while an ordinary bug fix bumps the patch version.
๐ License
This project is licensed under the GNU Affero General Public License v3.0 or later - see the COPYING file for details.
๐ Links
- Repository: https://github.com/ashcoft/extract
- Releases: https://github.com/ashcoft/extract/releases
- Upstream: https://github.com/LibreCodeCoop/extract
- Original author: Paul Lereverend